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).interval_widths() and
pretty_widths() make it easier to create nicely-spaced sets
of nested intervals.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.