Major changes:
subguides for geom_slab(), there are now subscales,
which can be used to adjust the limits or the expand parameter of the
thickness per-geometry sub-scales (in much the same way those
parameters can be set on scale_thickness_shared()) (#219).subscale_thickness,
subguide_slab, subguide_dots, and subguide_spike in the global
environment (#225).shapes in geom_blur_dots().stat_slabinterval() now use waiver()s so that they
can be set either in the call to the stat or in the call to the density
estimator (#220).right_closed and outermost_closed
arguments to density_histogram() (#238).Documentation:
Bug fixes:
check.aes and check.param to layer() so
that aesthetics can be used to carry data to later stages of the pipeline
without spurious warnings (#248).point_interval(<distribution>) supports tidy evaluation on the
.point and .interval arguments (#221).point_interval(<tibble>) always returns a tibble() (#224).Major changes:
geom_slabinterval() and geom_dotsinterval() families gain "sub-guides",
which can be passed to the subguide parameter to create axis annotations for
the thickness aesthetic (for slabs) and the dot count (for dots) (#183).weight aesthetic is now supported in stat_slabinterval(), including
weighted calculations for densities, CDFs, all interval types (quantile
intervals, highest density intervals, and highest density continuous intervals),
and all point summaries (mean, median, and mode) (#41). This includes support
for the upcoming weighted random variable type in the posterior package.geom_blur_dots(), which accepts an
sd aesthetic to set the standard deviation of the blur on each dot.
Intervals can also be used in place of blur by passing blur = "interval".
This geom is used by the new stat_mcse_dots() to show quantiles along with
their error using blur (#63).breaks_quantiles() histogram breaks function allows the construction
of quantile histograms with density_histogram(), stat_histinterval(), etc.scale_colour_ramp_continuous(), ...) now use
an explicit data type, partial_colour_ramp(), to encode color ramps and
their origin colors, and provide the ramp_colours() function for applying
colour ramps. This should make it easier to pass explicit color ramps
without using scale functions, and for packages building on {ggdist} to
use the colour ramp scales (#209).Minor changes:
"Scott" instead of
"Sturges", as "Sturges" tends to be too conservative (#214).at parameter to stat_spike() (or its names) now determines values of
an at computed variable, which can be mapped onto aesthetics via after_stat()
to more easily label spikes. (#203; thanks @mattansb for the suggestion).arrow parameter is now supported for intervals in geom_slabinterval()
(#206; thanks to @ASKurz for the suggestion).overflow in geom_dotsinterval() is now the new
"warn" mode, which works the same as "keep" except that it warns users
if the dots will overflow the geometry bounds and suggests solutions (#213).waiver() to use their default value (see auto_partial()).curve_interval() due to its use of grouped data frames and tidy selection to
specify which columns are conditional and which are joint (the use of grouped
data frames with point_interval() is less strictly necessary, and not used
by stats, so is easier to avoid as an absolute dependency).Documentation:
thickness
aesthetic with comprehensive examples of how slab scaling works (#205).Bug fixes:
Mode() works on analytical constant distributions.New features and enhancements:
layout = "bar" for geom_dotsinterval() that provides better bar
dotplots (with thanks to @sharoz for feedback; #190).bandwidth_dpi()) now fall back
to bandwidth_nrd0() when they fail, with a warning that suggests trying
a dotplot or histogram (as these failures tend to happen on data that is not
a good candidate for a density plot in the first place) (#196).Bug fixes:
scale_side_mirrored() supports start = "left" and start = "right"geom_spike() draws the point on the correct end of the line depending on side.guide_rampbar() for ggplot2 > 3.4.2 (#186). Thanks to @teunbrand.size aesthetic to be overridden for the geom_dots() legend.hdi() supports constants. (#194)Breaking changes: The following changes, mostly due to new default density
estimators, may cause some plots on sample data to change. Changes should usually
be small, and generally should result in more accurate density estimation. Revert
to the old behavior by setting density = density_unbounded(bandwidth = "nrd0").
stat_slabinterval() now uses density_bounded() as its default density
estimator, which uses a bounded density estimator that also estimates the
bounds of the data. The default bandwidth estimator is also now bandwidth_dpi(),
which is the Sheather-Jones direct plug-in estimator (the same as
stats::bw.SJ(..., method = "dpi")). These changes may cause existing charts
using densities to change; usually only slightly. These changes should be worth
it, as they should drastically improve the accuracy of density estimates,
especially on bounded data, and should have little noticeable impact on densities
on unbounded data.density_bounded() now estimates bounds from the data when not provided
(i.e. when one of bounds is NA). See the bounder_ functions (e.g.
bounder_cdf(), bounder_cooke()) for more on bounds estimation.Mode() and hdi() estimators based on bounded density estimator.New features and enhancements:
hdci() estimator using quantile estimation.density_histogram(), a histogram
density estimator. Finer-grained control of bin positions is now possible
using the breaks argument (including the new breaks_fixed() for manually-specified
bin widths) and the align argument (including the new align_boundary() and
align_center() for choosing how to align bin positions to reference points). (#118)geom_spike() and stat_spike() for adding spike annotations to slabs
created with geom_slabinterval() or stat_slabinterval(). See example
in vignette("slabinterval"). (#58, #124)parse_dist() now outputs distributional objects in a .dist_obj column in
addition to the name-plus-arguments (.dist+.args) format, and these objects respect truncation
parameters from prior specifications. This makes it easier to visualize standard
deviation priors, for example, giving a better solution to #20.marginalize_lkjcorr() adjusts the .dist_obj column output by parse_dist()
in addition to the .dist and .args columns.geom_lineribbon() now obeys the order aesthetic, allowing you to arbitrarily
set the draw order of ribbons (#171). Enabled by this change, stat_lineribbon()
now sets order = after_stat(level) by default, making its draw order more correct
by ensuring all ribbons of the same level are drawn together.cli.adapt parameter;
note that it is unsupported and both the implementation and interface are
highly likely to change.Deprecations:
slab_type parameter for stat_slabinterval() is now deprecated in favor
of mapping the corresponding computed variable (pdf or cdf) onto the desired
aesthetic. For slab_type = "histogram", use the pdf computed variable
combined with the new density_histogram() density estimator (e.g. set
density = "histogram"). (#165)Bug fixes:
stat_interval(). (#168)curve_interval() works with posterior::rvars. (#158)geom_lineribbon() draw order is now correct even when some portions of a
ribbon has NA widths. (#171)New features and enhancements:
stat_slabinterval() and
stat_dotsinterval(), including dist_categorical(), dist_bernoulli(),
and the upcoming posterior::rvar_factor() type. (#108)geom_dotsinterval():
layout = "hex" allows a hexagonal circle-packing style layout (#161).smooth parameter, including
smooth = "bounded" / smooth = "unbounded" (for "density dotplots") and
smooth = "discrete" / smooth = "bar" (for improved layout of large-n
discrete distributions). (#161)overlaps = "keep" option disables bin/dot nudging in "bin", "hex",
and "weave" layouts. This means layout = "weave" with overlaps = "keep"
will yield exact dot positions. (#161)"weave" layout now works properly with side = "both"binwidth of 1 for discrete distributions (#159)overflow = "compress" allows layouts to be compressed to fit into the
geom bounds if a user-specified binwidth would otherwise cause the dots
to exceed the geom bounds. (#162)geom_dotsinterval(): geom_swarm() and geom_weave().
Both can be used to quickly create "beeswarm"-like plots.side aesthetic, scale_side_mirrored(), makes it
easier to create mirrored slabs and dotplots. (#142)stat_slabinterval() via the
density argument, including a new bounded density estimator (density_bounded()).
(#113)size and linewidth aesthetics in ggplot2 3.4,
the following aesthetics have been updated (#138):
interval_size is now linewidthslab_size is now slab_linewidthgeom_slab(), geom_dots(), and geom_lineribbon(), size is now linewidthstats: the Pr_() and p_() functions can be used to generate
after_stat() expressions in terms of ggdist computed variables; e.g.
aes(thickness = !!Pr_(X <= x)) maps the CDF of the distribution onto the
thickness aesthetic; aes(thickness = !!p_(x)) maps the PDF onto the
thickness aesthetic. (#160)point_interval(), smooth_...,
and density_.... See help("automatic-partial-functions").point_interval() on grouped data frames. (#154)Documentation:
stat() have been replaced with after_stat() to be consistent with
the deprecation of stat() in ggplot2 3.4.New features and enhancements:
stat_slabinterval() can now be shared across
sub-geometries:
.width and level computed variables can now be used in slab / dots
sub-geometries. These values correspond to the smallest interval computed
in the interval sub-geometry containing that portion of the slab. This
gives a more flexible alternative to using cut_cdf_qi() to create densities
filled according to a set of intervals (this approach which also works on
highest-density intervals, which cut_cdf_qi() does not). Examples in
vignette("slabinterval") have been updated to use the new approach, and
an example has been added to vignette("dotsinterval") showing how to
color dots by intervals.options(ggdist.experimental.slab_data_in_intervals = TRUE),
the pdf and cdf computed variables can now be used in interval
sub-geometries to get the PDF and CDF at the point summary. pdf_min,
pdf_max, cdf_min, and cdf_max also give the PDF and CDF at the lower
and upper ends of the interval. An example in vignette("lineribbon")
shows how to use this to make lineribbon gradients whose color approximates
density (as opposed to the classic gradient fan chart examples already
in that vignette, where color approximates the CDF).scale_thickness_shared() is now provided to allow the thickness scale to be
shared across geometries, making certain plot types easier to create
(e.g. plots of prior and posterior densities together). See
vignette("slabinterval") for an example.thickness is less than 0 it is normalized to have a minimum of zero when
normalization is turned on; this makes it easier to use slab functions that
go below zero. A new example in vignette("slabinterval") shows how to use
this to create raindrop plots.geom_dotsinterval(layout = "bin")
can now be set using the order aesthetic. This makes it possible to create
"stacked" dotplots by mapping a discrete variable onto the order aesthetic
(#132). As part of this change, bin_dots() now maintains the original data
order within bins when layout = "bin". See an example in
vignette("dotsinterval").verbose = TRUE flag in geom_dotsinterval() outputs the selected
binwidth in both data units and normalized parent coordinates. This may be
useful if you want to start with an automatically-selected bin width and then
adjust it manually. Though note: if you just want to scale the selected
bin width to fit within a desired area, it is probably better to use scale,
and if you want to provide constraints on the bin width, you can pass a
2-vector to binwidth.expand argument in stat_slabinterval() can now take a length-two logical
vector to control expansion to the lower and upper limits respectively (#129).
Thanks to @teunbrand.geom_dotsinterval() now supports the family aesthetic for setting the font
used to display its dots (based on a conversation with @gdbassett).guide_rampbar() for creating gradient-like legends for
continuous color/fill ramp scales, based on ggplot2::guide_colorbar().
See an example in vignette("lineribbon").Bug fixes:
NAs in the thickness aesthetic of a slab, these are now
rendered as gaps in the slab (#129).Bug fixes:
point_interval argument of stat_slabinterval(),
a function with that name will be searched for in the calling environment and
the ggdist package environment. The latter ensures that stats work when
ggdist is loaded but not attached to the search path (#128).New features and enhancements:
stat_sample_... and stat_dist_... families of stats have been merged (#83).
stat_dist_... stats are deprecated in favor of their stat_... counterparts,
which now understand the dist, args, and arg1...arg9 aesthetics.xdist and ydist can now be used in place of the dist aesthetic to
specify the axis one is mapping a distribution onto (dist may be
deprecated in the future).x or y aesthetics now raise a helpful
error message suggesting you probably want to use xdist or ydist.expand parameter to stat_slabinterval() allows explicitly setting
whether or not the slab is expanded to the limits of the scale (rather than
implicitly setting this based on slab_type).point_interval() family of functions can now be passed distributional
and posterior::rvar() objects, meaning that means and modes (in addition
to medians) and highest-density intervals (in addition to quantile intervals)
can now be visualized for analytical distributions.
rvars will generate
a .index column when passed to point_interval() functions (#111).
Based on a suggestion from @mitchelloharawild.stat_ribbon() provided as a shortcut stat for stat_lineribbon() with
no line (#48). Also, if you supply only an x or y aesthetic to
geom_lineribbon(), you will get ribbons without a line (#127).ul() (upper
limit) or ll() (lower limit), e.g. with point_interval() explicitly or
via mean_ll(), median_ll(), mode_ll(), mean_ul(), median_ul(),
or mode_ul() (#49).scale more often.1.07 for dot sizes is now exposed as
the default value of the dotsize parameter instead of being applied
internally. This fudge factor tends (in my opinion) to make dotplots look a
bit better due to the visual distance between circles, but is (I think)
better used as an explicit value than an implicit one, hence the change.
This may create subtle changes to plots that use the dotsize or stackratio
parameters, but allows those parameters to have a more precise
geometric interpretation.Documentation:
stat_dotsinterval() sub-family: vignette("dotsinterval") (#120).stat_slabinterval() and
geom_slabinterval() family: each shortcut stat/geom now has its own documentation
page that comprehensively lists all parameters, aesthetics, and computed variables,
including those pulled in via ... from typically-paired geoms. These docs are
auto-generated and should be easy to maintain going forward. (#36)stat_lineribbon() and geom_lineribbon() family now also has separate
documentation pages with a comprehensive listing of aesthetics and parameters (#107).vignette("slabinterval") using the new expand
parameter (#115).Deprecations and removals:
.prob argument, a long-deprecated alias for .width, was removed.limits_function, limits_args, slab_function, slab_args, interval_function,
and interval_args arguments to stat_slabinterval() were removed: these were
largely internal-use parameters only needed by subclasses of the base class for
creating shortcut stats, yet added a lot of noise to the documentation, so these
were replaced with the $compute_limits(), $compute_slabs(), and
$compute_intervals() methods on the new AbstractStatSlabinterval
internal base class.Bug fixes:
NAs for analytical distributions."bin" and "weave"
layouts could be incorrect with aesthetics mapped at a sub-bin level.stackratios that are not equal to 1 are now accounted for in
find_dotplot_binwidth() (i.e. automatic dotplot bin width selection).fill_ramp aesthetic ramps them to the same color.Bug fixes:
distributional >= 0.2.2.9000 (#91).stat_sample_slabinterval() (#98).linearGradient() function on R < 4.1.geom_slabinterval().Breaking changes:
geom_slabinterval() family geoms when using position_dodge()
is now slightly different in order to match up with how other geoms are positioned (#85).
This may slightly change existing charts that use position = "dodge", and in
some cases may cause slabs to be drawn slightly outside plot boundaries, but makes
it much easier to combine geom_slabinterval() with other geoms in the expected
way. If dodging more similar to the old approach is needed, use the new
"justification-preserving dodge", position_dodgejust(), in place of position_dodge().New features:
geom_slabinterval(), side, justification, and scale can now be
used as aesthetics instead of parameters, allowing them to vary across slabs
within the same geom.fills within a slab in geom_slabinterval() can now be drawn as
true gradients rather than segmented polygons in R >= 4.1 by setting
fill_type = "gradient". This substantially improves the appearance of
gradient fills in graphics engines that support it (#44).stat_dist_slabinterval() and company now detect discrete distributions and
display them as histograms (#19).geom_dotsinterval() now adjusts bin widths on discrete distributions when
they would result in bins that are taller than the allocated space to ensure
that they fit within the required space (#42).geom_dotsinterval()
bin width by passing a vector of two values to the binwidth parameter.geom_dotsinterval() has been
factored out and exported as find_dotplot_binwidth() and bin_dots() for
others to use (#77).curve_interval() used a common (but naive) approach to finding
a cutoff on data depth to identify the X% "deepest" curves, simply taking the
envelope around the X% quantile of curves ranked by depth. This is quite
conservative and tends to create intervals that are too wide; curve_interval()
now searches for a cutoff in data depth such that X% of curves are contained
within its envelope (#67).point_interval() and company now accept distributional objects and
posterior::rvar()s (full support for distributional objects requires
distributional > 0.2.2).New documentation:
Substantial improvements to the documentation of aesthetics and computed
variables in geom_slabinterval(), stat_slabinterval(), and company, listing
all custom aesthetics, computed variables, and their usage.
Several new examples in vignette("slabinterval"), including "rain cloud"
plots and an example of histograms for discrete analytical distributions.
Bug fixes:
stat_dist_slabinterval() preserves group order (#88).n for stat_sample_slabinterval().NA handling across the geoms (#74, #51).New features:
"weave" and "swarm" layouts for dots geoms (#64). These provide
alternative layouts that keep datapoints in their actual positions on the
data axis. The "weave" layout maintains rows but not columns and works well
for quantile dotplots; the "swarm" layout uses the "compactswarm" method from
beeswarm::beeswarm() (courtesy James Trimble) and works well on sample data.
See the dotplot section of vignette("slabinterval") for comparisons.unit() to specify bin widths manually for dots geoms and stats,
which can be helpful when you need dotplots across facets to have the same bin width
(#53).New documentation:
fill_ramp in vignette("lineribbon").vignette("slabinterval").vignette("slabinterval").Bug fixes:
New features:
pdf and cdf computed variables for the stat_sample_slabinterval() subfamily. See
new examples of usage in the last section of vignette("slabinterval"). (#11)cut_cdf_qi() for creating (amongst other things) interval-filled halfeyes, in the
style of bayesplot::mcmc_areas() (#11)fill_ramp and color_ramp scales to geom_slabinterval() and geom_lineribbon() families,
making it easier to separate group colors from interval/density/CDF colors. See new examples in
vignette("slabinterval"), vignette("lineribbon"), and vignette("freq-uncertainty-vis"). (#16)brms::brmsprior implementation for parse_dist() (#34)New documentation:
vignette("freq-uncertainty-vis") now uses distributional::dist_student_t() (#14)vignette("slabinterval") (#23)vignette("lineribbon") (#22)interval_size_range argument in docs (#35)Bug fixes:
na.rm support to curve_interval() (#22)New features and documentation:
curve_interval() for generating curvewise (joint) intervals for curve boxplots (#22)vignette("lineribbon") describing geom_lineribbon(), stat_lineribbon(),
stat_dist_lineribbon(), and curve_interval().Bug fixes:
dist aesthetics that are factors (#25)vignette("slabinterval") (#14).stat_dist_... geoms now calculate pdf and cdf columns to allow mashup geoms that involve both
functions, such as Correll-style gradient plots combined with violins, as in Helske et al. (#11).stat_dist_... geoms should now work with gganimate (#15).broom::augment() defaulting to se_fit = FALSE.point_interval()), vignette("slabinterval"), and
vignette("freq-uncertainty-vis"). Tidybayes will retain all other functions, and will re-export all
ggdist functions for now.h-suffix geoms are now
deprecated. Those geoms have been left in tidybayes and give a deprecation warning when used; they
cannot be used from ggdist directly.geom_interval(), geom_pointinterval(), and geom_lineribbon() no longer automatically set the
ymin and ymax aesthetics if .lower or .upper are present in the data. This allows them to work
better with automatic orientation detection (and was a bad feature to have existed in the first place
anyway). The deprecated tidybayes::geom_intervalh() and tidybayes::geom_pointintervalh() still
automatically set those aesthetics, since they are deprecated anyway (so supporting the old behavior
is fine in these functions).geom_lineribbon()/stat_lineribbon() now supports a step argument for creating stepped lineribbons.
H/T to Solomon Kurz for the suggestion.ggdist now has its own implementation of the scaled and shifted Student's t distribution (dstudent_t(),
qstudent_t(), etc), since it is very useful for visualizing confidence distributions.