Package 'ggdist'

Visualizations of Distributions and Uncertainty

Description

ggdist is an R package that aims to make it easy to integrate popular Bayesian modeling methods into a tidy data + ggplot workflow.

Details

ggdist is an R package that provides a flexible set of ggplot2 geoms and stats designed especially for visualizing distributions and uncertainty. It is designed for both frequentist and Bayesian uncertainty visualization, taking the view that uncertainty visualization can be unified through the perspective of distribution visualization: for frequentist models, one visualizes confidence distributions or bootstrap distributions (see vignette("freq-uncertainty-vis")); for Bayesian models, one visualizes probability distributions (see vignette("tidybayes", package = "tidybayes")).

The geom_slabinterval() / stat_slabinterval() family (see vignette("slabinterval")) makes it easy to visualize point summaries and intervals, eye plots, half-eye plots, ridge plots, CCDF bar plots, gradient plots, histograms, and more.

The geom_dotsinterval() / stat_dotsinterval() family (see vignette("dotsinterval")) makes it easy to visualize dot+interval plots, Wilkinson dotplots, beeswarm plots, and quantile dotplots.

The geom_lineribbon() / stat_lineribbon() family (see vignette("lineribbon")) makes it easy to visualize fit lines with an arbitrary number of uncertainty bands.

Author(s)

Maintainer: Matthew Kay [email protected]

Other contributors:

• Brenton M. Wiernik [email protected] [contributor]

See Also

Useful links:

• https://mjskay.github.io/ggdist/

• https://github.com/mjskay/ggdist/

• Report bugs at https://github.com/mjskay/ggdist/issues/new

---

Break (bin) alignment methods

Description

Methods for aligning breaks (bins) in histograms, as used in the align argument to density_histogram().

Supports automatic partial function application with waived arguments.

Usage

align_none(breaks)

align_boundary(breaks, at = 0)

align_center(breaks, at = 0)

Arguments

breaks	<numeric> A sorted vector of breaks (bin edges).
at	<scalar numeric> The alignment point. For align_boundary(): align breaks so that a bin edge lines up with at. For align_center(): align breaks so that the center of a bin lines up with at.

Details

These functions take a sorted vector of equally-spaced breaks giving bin edges and return a numeric offset which, if subtracted from breaks, will align them as desired:

• align_none() performs no alignment (it always returns 0).

• align_boundary() ensures that a bin edge lines up with at.

• align_center() ensures that a bin center lines up with at.

For align_boundary() (respectively align_center()), if no bin edge (or center) in the range of breaks would line up with at, it ensures that at is an integer multiple of the bin width away from a bin edge (or center).

Value

A scalar numeric returning an offset to be subtracted from breaks.

See Also

density_histogram(), breaks

Examples

library(ggplot2)

set.seed(1234)
x = rnorm(200, 1, 2)

# If we manually specify a bin width using breaks_fixed(), the default
# alignment (align_none()) will not align bin edges to any "pretty" numbers.
# Here is a comparison of the three alignment methods on such a histogram:
ggplot(data.frame(x), aes(x)) +
  stat_slab(
    aes(y = "align_none()\nor 'none'"),
    density = "histogram",
    breaks = breaks_fixed(width = 1),
    outline_bars = TRUE,
    # no need to specify align; align_none() is the default
    color = "black",
  ) +
  stat_slab(
    aes(y = "align_center(at = 0)\nor 'center'"),
    density = "histogram",
    breaks = breaks_fixed(width = 1),
    align = align_center(at = 0),   # or align = "center"
    outline_bars = TRUE,
    color = "black",
  ) +
  stat_slab(
    aes(y = "align_boundary(at = 0)\nor 'boundary'"),
    density = "histogram",
    breaks = breaks_fixed(width = 1),
    align = align_boundary(at = 0), # or align = "boundary"
    outline_bars = TRUE,
    color = "black",
  ) +
  geom_point(aes(y = 0.7), alpha = 0.5) +
  labs(
    subtitle = "ggdist::stat_slab(density = 'histogram', ...)",
    y = "align =",
    x = NULL
  ) +
  geom_vline(xintercept = 0, linetype = "22", color = "red")

---

Automatic partial function application in ggdist

Description

Several ggdist functions support automatic partial application: when called, if all of their required arguments have not been provided, the function returns a modified version of itself that uses the arguments passed to it so far as defaults. Technically speaking, these functions are essentially "Curried" with respect to their required arguments, but I think "automatic partial application" gets the idea across more clearly.

Functions supporting automatic partial application include:

• The point_interval() family, such as median_qi(), mean_qi(), mode_hdi(), etc.

• The smooth_ family, such as smooth_bounded(), smooth_unbounded(), smooth_discrete(), and smooth_bar().

• The density_ family, such as density_bounded(), density_unbounded() and density_histogram().

• The align family.

• The breaks family.

• The bandwidth family.

• The blur family.

Partial application makes it easier to supply custom parameters to these functions when using them inside other functions, such as geoms and stats. For example, smoothers for geom_dots() can be supplied in one of three ways:

• as a suffix: geom_dots(smooth = "bounded")

• as a function: geom_dots(smooth = smooth_bounded)

• as a partially-applied function with options: geom_dots(smooth = smooth_bounded(kernel = "cosine"))

Many other common arguments for ggdist functions work similarly; e.g. density, align, breaks, bandwidth, and point_interval arguments.

These function families (except point_interval()) also support passing waivers to their optional arguments: if waiver() is passed to any of these arguments, their default value (or the most recently-partially-applied non-waiver value) is used instead.

Use the auto_partial() function to create new functions that support automatic partial application.

Usage

auto_partial(f, name = NULL, waivable = TRUE)

Arguments

f	<function> Function to automatically partially-apply.
name	<string> Name of the function, to be used when printing.
waivable	<scalar logical> If TRUE, optional arguments that get passed a waiver() will keep their default value (or whatever non-waiver value has been most recently partially applied for that argument).

Value

A modified version of f that will automatically be partially applied if all of its required arguments are not given.

Examples

set.seed(1234)
x = rnorm(100)

# the first required argument, `x`, of the density_ family is the vector
# to calculate a kernel density estimate from. If it is not provided, the
# function is partially applied and returned as-is
density_unbounded()

# we could create a new function that uses half the default bandwidth
density_half_bw = density_unbounded(adjust = 0.5)
density_half_bw

# we can overwrite partially-applied arguments
density_quarter_bw_trimmed = density_half_bw(adjust = 0.25, trim = TRUE)
density_quarter_bw_trimmed

# when we eventually call the function and provide the required argument
# `x`, it is applied using the arguments we have "saved up" so far
density_quarter_bw_trimmed(x)

# create a custom automatically partially applied function
f = auto_partial(function(x, y, z = 3) (x + y) * z)
f()
f(1)
g = f(y = 2)(z = 4)
g
g(1)

# pass waiver() to optional arguments to use existing values
f(z = waiver())(1, 2)  # uses default z = 3
f(z = 4)(z = waiver())(1, 2)  # uses z = 4

---

Bandwidth estimators

Description

Bandwidth estimators for densities, used in the bandwidth argument to density functions (e.g. density_bounded(), density_unbounded()).

Supports automatic partial function application with waived arguments.

Usage

bandwidth_nrd0(x, ...)

bandwidth_nrd(x, ...)

bandwidth_ucv(x, ...)

bandwidth_bcv(x, ...)

bandwidth_SJ(x, ...)

bandwidth_dpi(x, ...)

Arguments

x

<numeric> Vector containing a sample.

...

Arguments passed on to stats::bw.SJ nb number of bins to use. lower,upper range over which to minimize. The default is almost always satisfactory. hmax is calculated internally from a normal reference bandwidth. method either "ste" ("solve-the-equation") or "dpi" ("direct plug-in"). Can be abbreviated. tol for method "ste", the convergence tolerance for uniroot. The default leads to bandwidth estimates with only slightly more than one digit accuracy, which is sufficient for practical density estimation, but possibly not for theoretical simulation studies.

Details

These are loose wrappers around the corresponding bw.-prefixed functions in stats. See, for example, bw.SJ().

bandwidth_dpi(), which is the default bandwidth estimator in ggdist, is the Sheather-Jones direct plug-in estimator, i.e. bw.SJ(..., method = "dpi").

With the exception of bandwidth_nrd0(), these estimators may fail in some cases, often when a sample contains many duplicates. If they do they will automatically fall back to bandwidth_nrd0() with a warning. However, these failures are typically symptomatic of situations where you should not want to use a kernel density estimator in the first place (e.g. data with duplicates and/or discrete data). In these cases consider using a dotplot (geom_dots()) or histogram (density_histogram()) instead.

Value

A single number giving the bandwidth

See Also

density_bounded(), density_unbounded().

---

Bin data values using a dotplot algorithm

Description

Bins the provided data values using one of several dotplot algorithms.

Usage

bin_dots(
  x,
  y,
  binwidth,
  heightratio = 1,
  stackratio = 1,
  layout = c("bin", "weave", "hex", "swarm", "bar"),
  side = c("topright", "top", "right", "bottomleft", "bottom", "left", "topleft",
    "bottomright", "both"),
  orientation = c("horizontal", "vertical", "y", "x"),
  overlaps = "nudge"
)

Arguments

x	<numeric> x values.
y	<numeric> y values (same length as x).
binwidth	<scalar numeric> Bin width.
heightratio	<scalar numeric> Ratio of bin width to dot height
stackratio	<scalar numeric> Ratio of dot height to vertical distance between dot centers
layout	<string> The layout method used for the dots. One of: "bin" (default): places dots on the off-axis at the midpoint of their bins as in the classic Wilkinson dotplot. This maintains the alignment of rows and columns in the dotplot. This layout is slightly different from the classic Wilkinson algorithm in that: (1) it nudges bins slightly to avoid overlapping bins and (2) if the input data are symmetrical it will return a symmetrical layout. "weave": uses the same basic binning approach of "bin", but places dots in the off-axis at their actual positions (unless overlaps = "nudge", in which case overlaps may be nudged out of the way). This maintains the alignment of rows but does not align dots within columns. "hex": uses the same basic binning approach of "bin", but alternates placing dots + binwidth/4 or - binwidth/4 in the off-axis from the bin center. This allows hexagonal packing by setting a stackratio less than 1 (something like 0.9 tends to work). "swarm": uses the "compactswarm" layout from beeswarm::beeswarm(). Does not maintain alignment of rows or columns, but can be more compact and neat looking, especially for sample data (as opposed to quantile dotplots of theoretical distributions, which may look better with "bin", "weave", or "hex"). "bar": for discrete distributions, lays out duplicate values in rectangular bars.
side	Which side to place the slab on. "topright", "top", and "right" are synonyms which cause the slab to be drawn on the top or the right depending on if orientation is "horizontal" or "vertical". "bottomleft", "bottom", and "left" are synonyms which cause the slab to be drawn on the bottom or the left depending on if orientation is "horizontal" or "vertical". "topleft" causes the slab to be drawn on the top or the left, and "bottomright" causes the slab to be drawn on the bottom or the right. "both" draws the slab mirrored on both sides (as in a violin plot).
orientation	<string> Whether the dots are laid out horizontally or vertically. Follows the naming scheme of geom_slabinterval(): "horizontal" assumes the data values for the dotplot are in the x variable and that dots will be stacked up in the y direction. "vertical" assumes the data values for the dotplot are in the y variable and that dots will be stacked up in the x direction. For compatibility with the base ggplot naming scheme for orientation, "x" can be used as an alias for "vertical" and "y" as an alias for "horizontal".
overlaps	<string> How to handle overlapping dots or bins in the "bin", "weave", and "hex" layouts (dots never overlap in the "swarm" or "bar" layouts). For the purposes of this argument, dots are only considered to be overlapping if they would be overlapping when dotsize = 1 and stackratio = 1; i.e. if you set those arguments to other values, overlaps may still occur. One of: "keep": leave overlapping dots as they are. Dots may overlap (usually only slightly) in the "bin", "weave", and "hex" layouts. "nudge": nudge overlapping dots out of the way. Overlaps are avoided using a constrained optimization which minimizes the squared distance of dots to their desired positions, subject to the constraint that adjacent dots do not overlap.

Value

A data.frame with three columns:

• x: the x position of each dot

• y: the y position of each dot

• bin: a unique number associated with each bin (supplied but not used when layout = "swarm")

See Also

find_dotplot_binwidth() for an algorithm that finds good bin widths to use with this function; geom_dotsinterval() for geometries that use these algorithms to create dotplots.

Examples

library(dplyr)
library(ggplot2)

x = qnorm(ppoints(20))
bin_df = bin_dots(x = x, y = 0, binwidth = 0.5, heightratio = 1)
bin_df

# we can manually plot the binning above, though this is only recommended
# if you are using find_dotplot_binwidth() and bin_dots() to build your own
# grob. For practical use it is much easier to use geom_dots(), which will
# automatically select good bin widths for you (and which uses
# find_dotplot_binwidth() and bin_dots() internally)
bin_df %>%
  ggplot(aes(x = x, y = y)) +
  geom_point(size = 4) +
  coord_fixed()

---

Blur functions for blurry dot plots

Description

Methods for constructing blurs, as used in the blur argument to geom_blur_dots() or stat_mcse_dots().

Supports automatic partial function application with waived arguments.

Usage

blur_gaussian(x, r, sd)

blur_interval(x, r, sd, .width = 0.95)

Arguments

x	<numeric> Vector of positive distances from the center of the dot (assumed to be 0) to evaluate blur function at.
r	<scalar numeric> Radius of the dot that is being blurred.
sd	<scalar numeric> Standard deviation of the dot that is being blurred.
.width	<scalar numeric> For blur_interval(), a probability giving the width of the interval.

Details

These functions are passed x, r, and sd when geom_blur_dots() draws in order to create a radial gradient representing each dot in the dotplot. They return values between 0 and 1 giving the opacity of the dot at each value of x.

blur_gaussian() creates a dot with radius r that has a Gaussian blur with standard deviation sd applied to it. It does this by calculating $\alpha(x; r, \sigma)$, the opacity at distance $x$ from the center of a dot with radius $r$ that has had a Gaussian blur with standard deviation $\sigma$ = sd applied to it:

$\alpha(x; r, \sigma) = \Phi \left(\frac{x + r}{\sigma} \right) - \Phi \left(\frac{x - r}{\sigma} \right)$

blur_interval() creates an interval-type representation around the dot at 50% opacity, where the interval is a Gaussian quantile interval with mass equal to .width and standard deviation sd.

Value

A vector with the same length as x giving the opacity of the radial gradient representing the dot at each x value.

See Also

geom_blur_dots() and stat_mcse_dots() for geometries making use of blur functions.

Examples

# see examples in geom_blur_dots()

---

Estimate bounds of a distribution using the CDF of its order statistics

Description

Estimate the bounds of the distribution a sample came from using the CDF of the order statistics of the sample. Use with the bounder argument to density_bounded().

Supports automatic partial function application with waived arguments.

Usage

bounder_cdf(x, p = 0.01)

Arguments

x	<numeric> Sample to estimate the bounds of.
p	<scalar numeric> in $[0,1]$: Percentile of the order statistic distribution to use as the estimate. p = 1 will return range(x); p = 0.5 will give the median estimate, p = 0 will give a very wide estimate (effectively treating the distribution as unbounded when used with density_bounded()).

Details

bounder_cdf() uses the distribution of the order statistics of $X$ to estimate where the first and last order statistics (i.e. the min and max) of this distribution would be, assuming the sample x is the distribution. Then, it adjusts the boundary outwards from min(x) (or max(x)) by the distance between min(x) (or max(x)) and the nearest estimated order statistic.

Taking $X$ = x, the distributions of the first and last order statistics are:

$\begin{array}{rcl} F_{X_{(1)}}(x) &=& 1 - \left[1 - F_X(x)\right]^n\\ F_{X_{(n)}}(x) &=& F_X(x)^n \end{array}$

Re-arranging, we can get the inverse CDFs (quantile functions) of each order statistic in terms of the quantile function of $X$ (which we can estimate from the data), giving us an estimate for the minimum and maximum order statistic:

$\begin{array}{rcrcl} \hat{x_1} &=& F_{X_{(1)}}^{-1}(p) &=& F_X^{-1}\left[1 - (1 - p)^{1/n}\right]\\ \hat{x_n} &=& F_{X_{(n)}}^{-1}(p) &=& F_X^{-1}\left[p^{1/n}\right] \end{array}$

Then the estimated bounds are:

$\left[2\min(x) - \hat{x_1}, 2\max(x) - \hat{x_n} \right]$

These bounds depend on $p$, the percentile of the distribution of the order statistic used to form the estimate. While $p = 0.5$ (the median) might be a reasonable choice (and gives results similar to bounder_cooke()), this tends to be a bit too aggressive in "detecting" bounded distributions, especially in small sample sizes. Thus, we use a default of $p = 0.01$, which tends to be very conservative in small samples (in that it usually gives results roughly equivalent to an unbounded distribution), but which still performs well on bounded distributions when sample sizes are larger (in the thousands).

Value

A length-2 numeric vector giving an estimate of the minimum and maximum bounds of the distribution that x came from.

See Also

The bounder argument to density_bounded().

Other bounds estimators: bounder_cooke(), bounder_range()

---

Estimate bounds of a distribution using Cooke's method

Description

Estimate the bounds of the distribution a sample came from using Cooke's method. Use with the bounder argument to density_bounded().

Supports automatic partial function application with waived arguments.

Usage

bounder_cooke(x)

Arguments

x	<numeric> Sample to estimate the bounds of.

Details

Estimate the bounds of a distribution using the method from Cooke (1979); i.e. method 2.3 from Loh (1984). These bounds are:

$\left[\begin{array}{l} 2X_{(1)} - \sum_{i = 1}^n \left[\left(1 - \frac{i - 1}{n}\right)^n - \left(1 - \frac{i}{n}\right)^n \right] X_{(i)}\\ 2X_{(n)} - \sum_{i = 1}^n \left[\left(1 - \frac{n - i}{n}\right)^n - \left(1 - \frac{n + 1 - i}{n} \right)^n\right] X_{(i)} \end{array}\right]$

Where $X_{(i)}$ is the $i$th order statistic of x (i.e. its $i$th-smallest value).

Value

A length-2 numeric vector giving an estimate of the minimum and maximum bounds of the distribution that x came from.

References

Cooke, P. (1979). Statistical inference for bounds of random variables. Biometrika 66(2), 367–374. doi:10.1093/biomet/66.2.367.

Loh, W. Y. (1984). Estimating an endpoint of a distribution with resampling methods. The Annals of Statistics 12(4), 1543–1550. doi:10.1214/aos/1176346811

See Also

The bounder argument to density_bounded().

Other bounds estimators: bounder_cdf(), bounder_range()

---

Estimate bounds of a distribution using the range of the sample

Description

Estimate the bounds of the distribution a sample came from using the range of the sample. Use with the bounder argument to density_bounded().

Supports automatic partial function application with waived arguments.

Usage

bounder_range(x)

Arguments

x	<numeric> Sample to estimate the bounds of.

Details

Estimate the bounds of a distribution using range(x).

Value

A length-2 numeric vector giving an estimate of the minimum and maximum bounds of the distribution that x came from.

See Also

The bounder argument to density_bounded().

Other bounds estimators: bounder_cdf(), bounder_cooke()

---

Break (bin) selection algorithms for histograms

Description

Methods for determining breaks (bins) in histograms, as used in the breaks argument to density_histogram().

Supports automatic partial function application with waived arguments.

Usage

breaks_fixed(x, weights = NULL, width = 1)

breaks_Sturges(x, weights = NULL)

breaks_Scott(x, weights = NULL)

breaks_FD(x, weights = NULL, digits = 5)

breaks_quantiles(x, weights = NULL, max_n = "Scott", min_width = 0.5)

Arguments

x	<numeric> Sample values.
weights	<numeric | NULL> Optional weights to apply to x, which will be normalized to sum to 1.
width	<scalar numeric> For breaks_fixed(), the desired bin width.
digits	<scalar numeric> For breaks_FD(), the number of significant digits to keep when rounding in the Freedman-Diaconis algorithm. For an explanation of this parameter, see the documentation of the corresponding parameter in grDevices::nclass.FD().
max_n	<scalar numeric | function | string> For breaks_quantiles(), either a scalar numeric giving the maximum number of bins, or another breaks function (or string giving the suffix of the name of a function prefixed with "breaks_") that will return the maximum number of bins. breaks_quantiles() will construct at most max_n bins.
min_width	<scalar numeric> For breaks_quantiles(), a numeric between 0 and 1 giving the minimum bin width as a proportion of diff(range(x)) / max_n.

Details

These functions take a sample and its weights and return a value suitable for the breaks argument to density_histogram() that will determine the histogram breaks.

• breaks_fixed() allows you to manually specify a fixed bin width.

• breaks_Sturges(), breaks_Scott(), and breaks_FD() implement weighted versions of their corresponding base functions. They return a scalar numeric giving the number of bins. See nclass.Sturges(), nclass.scott(), and nclass.FD().

• breaks_quantiles() constructs irregularly-sized bins using max_n + 1 (possibly weighted) quantiles of x. The final number of bins is at most max_n, as small bins (ones whose bin width is less than half the range of the data divided by max_n times min_width) will be merged into adjacent bins.

Value

Either a single number (giving the number of bins) or a vector giving the edges between bins.

See Also

density_histogram(), align

Examples

library(ggplot2)

set.seed(1234)
x = rnorm(2000, 1, 2)

# Let's compare the different break-selection algorithms on this data:
ggplot(data.frame(x), aes(x)) +
  stat_slab(
    aes(y = "breaks_fixed(width = 0.5)"),
    density = "histogram",
    breaks = breaks_fixed(width = 0.5),
    outline_bars = TRUE,
    color = "black",
  ) +
  stat_slab(
    aes(y = "breaks_Sturges()\nor 'Sturges'"),
    density = "histogram",
    breaks = "Sturges",
    outline_bars = TRUE,
    color = "black",
  ) +
  stat_slab(
    aes(y = "breaks_Scott()\nor 'Scott'"),
    density = "histogram",
    breaks = "Scott",
    outline_bars = TRUE,
    color = "black",
  ) +
  stat_slab(
    aes(y = "breaks_FD()\nor 'FD'"),
    density = "histogram",
    breaks = "FD",
    outline_bars = TRUE,
    color = "black",
  ) +
  stat_slab(
    aes(y = "breaks_quantiles()\nor 'quantiles'"),
    density = "histogram",
    breaks = "quantiles",
    outline_bars = TRUE,
    color = "black",
  ) +
  geom_point(aes(y = 0.7), alpha = 0.5) +
  labs(
    subtitle = "ggdist::stat_slab(density = 'histogram', ...)",
    y = "breaks =",
    x = NULL
  )

---

Curvewise point and interval summaries for tidy data frames of draws from distributions

Description

Translates draws from distributions in a grouped data frame into a set of point and interval summaries using a curve boxplot-inspired approach.

Usage

curve_interval(
  .data,
  ...,
  .along = NULL,
  .width = 0.5,
  na.rm = FALSE,
  .interval = c("mhd", "mbd", "bd", "bd-mbd")
)

## S3 method for class 'matrix'
curve_interval(
  .data,
  ...,
  .along = NULL,
  .width = 0.5,
  na.rm = FALSE,
  .interval = c("mhd", "mbd", "bd", "bd-mbd")
)

## S3 method for class 'rvar'
curve_interval(
  .data,
  ...,
  .along = NULL,
  .width = 0.5,
  na.rm = FALSE,
  .interval = c("mhd", "mbd", "bd", "bd-mbd")
)

## S3 method for class 'data.frame'
curve_interval(
  .data,
  ...,
  .along = NULL,
  .width = 0.5,
  na.rm = FALSE,
  .interval = c("mhd", "mbd", "bd", "bd-mbd"),
  .simple_names = TRUE,
  .exclude = c(".chain", ".iteration", ".draw", ".row")
)

Arguments

.data	<data.frame | rvar | matrix> One of: A data frame (or grouped data frame as returned by dplyr::group_by()) that contains draws to summarize. A posterior::rvar vector. A matrix; in which case the first dimension should be draws and the second dimension values of the curve.
...	<bare language> Bare column names or expressions that, when evaluated in the context of .data, represent draws to summarize. If this is empty, then by default all columns that are not group columns and which are not in .exclude (by default ".chain", ".iteration", ".draw", and ".row") will be summarized. This can be numeric columns, list columns containing numeric vectors, or posterior::rvar()s.
.along	<tidyselect> Which columns are the input values to the function describing the curve (e.g., the "x" values). Intervals are calculated jointly with respect to these variables, conditional on all other grouping variables in the data frame. The default (NULL) causes curve_interval() to use all grouping variables in the input data frame as the value for .along, which will generate the most conservative intervals. However, if you want to calculate intervals for some function y = f(x) conditional on some other variable(s) (say, conditional on a factor g), you would group by g, then use .along = x to calculate intervals jointly over x conditional on g. To avoid selecting any variables as input values to the function describing the curve, use character(); this will produce conditional intervals only (the result in this case should be very similar to median_qi()). Currently only supported when .data is a data frame.
.width	<numeric> Vector of probabilities to use that determine the widths of the resulting intervals. If multiple probabilities are provided, multiple rows per group are generated, each with a different probability interval (and value of the corresponding .width column).
na.rm	<scalar logical> Should NA values be stripped before the computation proceeds? If FALSE (the default), the presence of NA values in the columns to be summarized will generally result in an error. If TRUE, NA values will be removed in the calculation of intervals so long as .interval is "mhd"; other methods do not currently support na.rm. Be cautious in applying this parameter: in general, it is unclear what a joint interval should be when any of the values are missing!
.interval	<string> The method used to calculate the intervals. Currently, all methods rank the curves using some measure of data depth, then create envelopes containing the .width% "deepest" curves. Available methods are: "mhd": mean halfspace depth (Fraiman and Muniz 2001). "mbd": modified band depth (Sun and Genton 2011): calls fda::fbplot() with method = "MBD". "bd": band depth (Sun and Genton 2011): calls fda::fbplot() with method = "BD2". "bd-mbd": band depth, breaking ties with modified band depth (Sun and Genton 2011): calls fda::fbplot() with method = "Both".
.simple_names	<scalar logical> When TRUE and only a single column / vector is to be summarized, use the name .lower for the lower end of the interval and .upper for the upper end. When FALSE and .data is a data frame, names the lower and upper intervals for each column x x.lower and x.upper.
.exclude	<character> Vector of names of columns to be excluded from summarization if no column names are specified to be summarized. Default ignores several meta-data column names used in ggdist and tidybayes.

Details

Intervals are calculated by ranking the curves using some measure of data depth, then using binary search to find a cutoff k such that an envelope containing the k% "deepest" curves also contains .width% of the curves, for each value of .width (note that k and .width are not necessarily the same). This is in contrast to most functional boxplot or curve boxplot approaches, which tend to simply take the .width% deepest curves, and are generally quite conservative (i.e. they may contain more than .width% of the curves).

See Mirzargar et al. (2014) or Juul et al. (2020) for an accessible introduction to data depth and curve boxplots / functional boxplots.

Value

A data frame containing point summaries and intervals, with at least one column corresponding to the point summary, one to the lower end of the interval, one to the upper end of the interval, the width of the interval (.width), the type of point summary (.point), and the type of interval (.interval).

Author(s)

Matthew Kay

References

Fraiman, Ricardo and Graciela Muniz. (2001). "Trimmed means for functional data". Test 10: 419–440. doi:10.1007/BF02595706.

Sun, Ying and Marc G. Genton. (2011). "Functional Boxplots". Journal of Computational and Graphical Statistics, 20(2): 316-334. doi:10.1198/jcgs.2011.09224

Mirzargar, Mahsa, Ross T Whitaker, and Robert M Kirby. (2014). "Curve Boxplot: Generalization of Boxplot for Ensembles of Curves". IEEE Transactions on Visualization and Computer Graphics. 20(12): 2654-2663. doi:10.1109/TVCG.2014.2346455

Juul Jonas, Kaare Græsbøll, Lasse Engbo Christiansen, and Sune Lehmann. (2020). "Fixed-time descriptive statistics underestimate extremes of epidemic curve ensembles". arXiv e-print. arXiv:2007.05035

See Also

point_interval() for pointwise intervals. See vignette("lineribbon") for more examples and discussion of the differences between pointwise and curvewise intervals.

Examples

library(dplyr)
library(ggplot2)

# generate a set of curves
k = 11 # number of curves
n = 201
df = tibble(
    .draw = rep(1:k, n),
    mean = rep(seq(-5,5, length.out = k), n),
    x = rep(seq(-15,15,length.out = n), each = k),
    y = dnorm(x, mean, 3)
  )

# see pointwise intervals...
df %>%
  group_by(x) %>%
  median_qi(y, .width = c(.5)) %>%
  ggplot(aes(x = x, y = y)) +
  geom_lineribbon(aes(ymin = .lower, ymax = .upper)) +
  geom_line(aes(group = .draw), alpha=0.15, data = df) +
  scale_fill_brewer() +
  ggtitle("50% pointwise intervals with point_interval()") +
  theme_ggdist()


# ... compare them to curvewise intervals
df %>%
  group_by(x) %>%
  curve_interval(y, .width = c(.5)) %>%
  ggplot(aes(x = x, y = y)) +
  geom_lineribbon(aes(ymin = .lower, ymax = .upper)) +
  geom_line(aes(group = .draw), alpha=0.15, data = df) +
  scale_fill_brewer() +
  ggtitle("50% curvewise intervals with curve_interval()") +
  theme_ggdist()

---

Categorize values from a CDF into quantile intervals

Description

Given a vector of probabilities from a cumulative distribution function (CDF) and a list of desired quantile intervals, return a vector categorizing each element of the input vector according to which quantile interval it falls into. NOTE: While this function can be used for (and was originally designed for) drawing slabs with intervals overlaid on the density, this is can now be done more easily by mapping the .width or level computed variable to slab fill or color. See Examples.

Usage

cut_cdf_qi(p, .width = c(0.66, 0.95, 1), labels = NULL)

Arguments

p	<numeric> Vector of values from a cumulative distribution function, such as values returned by p-prefixed distribution functions in base R (e.g. pnorm()), the cdf() function, or values of the cdf computed aesthetic from the stat_slabinterval() family of stats.
.width	<numeric> Vector of probabilities to use that determine the widths of the resulting intervals.
labels	<character | function | NULL> One of: A character vector giving labels (must be same length as .width) A function that takes numeric probabilities as input and returns labels as output (a good candidate might be scales::percent_format()). NULL to use the default labels (.width converted to a character vector).

Value

An ordered factor of the same length as p giving the quantile interval to which each value of p belongs.

See Also

See stat_slabinterval() and its shortcut stats, which generate cdf aesthetics that can be used with cut_cdf_qi() to draw slabs colored by their intervals.

Examples

library(ggplot2)
library(dplyr)
library(scales)
library(distributional)

theme_set(theme_ggdist())

# NOTE: cut_cdf_qi() used to be the recommended way to do intervals overlaid
# on densities, like this...
tibble(x = dist_normal(0, 1)) %>%
  ggplot(aes(xdist = x)) +
  stat_slab(
    aes(fill = after_stat(cut_cdf_qi(cdf)))
  ) +
  scale_fill_brewer(direction = -1)

# ... however this is now more easily and flexibly accomplished by directly
# mapping .width or level onto fill:
tibble(x = dist_normal(0, 1)) %>%
  ggplot(aes(xdist = x)) +
  stat_slab(
    aes(fill = after_stat(level)),
    .width = c(.66, .95, 1)
  ) +
  scale_fill_brewer()

# See vignette("slabinterval") for more examples. The remaining examples
# below using cut_cdf_qi() are kept for posterity.

# With a halfeye (or other geom with slab and interval), NA values will
# show up in the fill scale from the CDF function applied to the internal
# interval geometry data and can be ignored, hence na.translate = FALSE
tibble(x = dist_normal(0, 1)) %>%
  ggplot(aes(xdist = x)) +
  stat_halfeye(aes(
    fill = after_stat(cut_cdf_qi(cdf, .width = c(.5, .8, .95, 1)))
  )) +
  scale_fill_brewer(direction = -1, na.translate = FALSE)

# we could also use the labels parameter to apply nicer formatting
# and provide a better name for the legend, and omit the 100% interval
# if desired
tibble(x = dist_normal(0, 1)) %>%
  ggplot(aes(xdist = x)) +
  stat_halfeye(aes(
    fill = after_stat(cut_cdf_qi(
      cdf,
      .width = c(.5, .8, .95),
      labels = percent_format(accuracy = 1)
    ))
  )) +
  labs(fill = "Interval") +
  scale_fill_brewer(direction = -1, na.translate = FALSE)

---

Bounded density estimator using the reflection method

Description

Bounded density estimator using the reflection method.

Supports automatic partial function application with waived arguments.

Usage

density_bounded(
  x,
  weights = NULL,
  n = 501,
  bandwidth = "dpi",
  adjust = 1,
  kernel = "gaussian",
  trim = TRUE,
  bounds = c(NA, NA),
  bounder = "cdf",
  adapt = 1,
  na.rm = FALSE,
  ...,
  range_only = FALSE
)

Arguments

x	<numeric> Sample to compute a density estimate for.
weights	<numeric | NULL> Optional weights to apply to x.
n	<scalar numeric> The number of grid points to evaluate the density estimator at.
bandwidth	<scalar numeric | function | string> Bandwidth of the density estimator. One of: a numeric: the bandwidth, as the standard deviation of the kernel a function: a function taking x (the sample) and returning the bandwidth a string: the suffix of the name of a function starting with "bandwidth_" that will be used to determine the bandwidth. See bandwidth for a list.
adjust	<scalar numeric> Value to multiply the bandwidth of the density estimator by. Default 1.
kernel	<string> The smoothing kernel to be used. This must partially match one of "gaussian", "rectangular", "triangular", "epanechnikov", "biweight", "cosine", or "optcosine". See stats::density().
trim	<scalar logical> Should the density estimate be trimmed to the range of the data? Default TRUE.
bounds	<length-2 numeric> Min and max bounds. If a bound is NA, then that bound is estimated from the data using the method specified by bounder.
bounder	<function | string> Method to use to find missing (NA) bounds. A function that takes a numeric vector of values and returns a length-2 vector of the estimated lower and upper bound of the distribution. Can also be a string giving the suffix of the name of such a function that starts with "bounder_". Useful values include: "cdf": Use the CDF of the the minimum and maximum order statistics of the sample to estimate the bounds. See bounder_cdf(). "cooke": Use the method from Cooke (1979); i.e. method 2.3 from Loh (1984). See bounder_cooke(). "range": Use the range of x (i.e the min or max). See bounder_range().
adapt	<positive integer> (very experimental) The name and interpretation of this argument are subject to change without notice. If adapt > 1, uses an adaptive approach to calculate the density. First, uses the adaptive bandwidth algorithm of Abramson (1982) to determine local (pointwise) bandwidths, then groups these bandwidths into adapt groups, then calculates and sums the densities from each group. You can set this to a very large number (e.g. Inf) for a fully adaptive approach, but this will be very slow; typically something around 100 yields nearly identical results.
na.rm	<scalar logical> Should missing (NA) values in x be removed?
...	Additional arguments (ignored).
range_only	<scalar logical> If TRUE, the range of the output of this density estimator is computed and is returned in the ⁠$x⁠ element of the result, and c(NA, NA) is returned in ⁠$y⁠. This gives a faster way to determine the range of the output than density_XXX(n = 2).

Value

An object of class "density", mimicking the output format of stats::density(), with the following components:

• x: The grid of points at which the density was estimated.

• y: The estimated density values.

• bw: The bandwidth.

• n: The sample size of the x input argument.

• call: The call used to produce the result, as a quoted expression.

• data.name: The deparsed name of the x input argument.

• has.na: Always FALSE (for compatibility).

• cdf: Values of the (possibly weighted) empirical cumulative distribution function at x. See weighted_ecdf().

This allows existing methods for density objects, like print() and plot(), to work if desired. This output format (and in particular, the x and y components) is also the format expected by the density argument of the stat_slabinterval() and the smooth_ family of functions.

References

Cooke, P. (1979). Statistical inference for bounds of random variables. Biometrika 66(2), 367–374. doi:10.1093/biomet/66.2.367.

Loh, W. Y. (1984). Estimating an endpoint of a distribution with resampling methods. The Annals of Statistics 12(4), 1543–1550. doi:10.1214/aos/1176346811

See Also

Other density estimators: density_histogram(), density_unbounded()

Examples

library(distributional)
library(dplyr)
library(ggplot2)

# For compatibility with existing code, the return type of density_bounded()
# is the same as stats::density(), ...
set.seed(123)
x = rbeta(5000, 1, 3)
d = density_bounded(x)
d

# ... thus, while designed for use with the `density` argument of
# stat_slabinterval(), output from density_bounded() can also be used with
# base::plot():
plot(d)

# here we'll use the same data as above, but pick either density_bounded()
# or density_unbounded() (which is equivalent to stats::density()). Notice
# how the bounded density (green) is biased near the boundary of the support,
# while the unbounded density is not.
data.frame(x) %>%
  ggplot() +
  stat_slab(
    aes(xdist = dist), data = data.frame(dist = dist_beta(1, 3)),
    alpha = 0.25
  ) +
  stat_slab(aes(x), density = "bounded", fill = NA, color = "#d95f02", alpha = 0.5) +
  stat_slab(aes(x), density = "unbounded", fill = NA, color = "#1b9e77", alpha = 0.5) +
  scale_thickness_shared() +
  theme_ggdist()

# We can also supply arguments to the density estimators by using their
# full function names instead of the string suffix; e.g. we can supply
# the exact bounds of c(0,1) rather than using the bounds of the data.
data.frame(x) %>%
  ggplot() +
  stat_slab(
    aes(xdist = dist), data = data.frame(dist = dist_beta(1, 3)),
    alpha = 0.25
  ) +
  stat_slab(
    aes(x), fill = NA, color = "#d95f02", alpha = 0.5,
    density = density_bounded(bounds = c(0,1))
  ) +
  scale_thickness_shared() +
  theme_ggdist()

---

Histogram density estimator

Description

Histogram density estimator.

Supports automatic partial function application with waived arguments.

Usage

density_histogram(
  x,
  weights = NULL,
  breaks = "Scott",
  align = "none",
  outline_bars = FALSE,
  right_closed = TRUE,
  outermost_closed = TRUE,
  na.rm = FALSE,
  ...,
  range_only = FALSE
)

Arguments

x	<numeric> Sample to compute a density estimate for.
weights	<numeric | NULL> Optional weights to apply to x.
breaks	<numeric | function | string> Determines the breakpoints defining bins. Default "Scott". Similar to (but not exactly the same as) the breaks argument to graphics::hist(). One of: A scalar (length-1) numeric giving the number of bins A vector numeric giving the breakpoints between histogram bins A function taking x and weights and returning either the number of bins or a vector of breakpoints A string giving the suffix of a function that starts with "breaks_". ggdist provides weighted implementations of the "Sturges", "Scott", and "FD" break-finding algorithms from graphics::hist(), as well as breaks_fixed() for manually setting the bin width. See breaks. For example, breaks = "Sturges" will use the breaks_Sturges() algorithm, breaks = 9 will create 9 bins, and breaks = breaks_fixed(width = 1) will set the bin width to 1.
align	<scalar numeric | function | string> Determines how to align the breakpoints defining bins. Default "none" (performs no alignment). One of: A scalar (length-1) numeric giving an offset that is subtracted from the breaks. The offset must be between 0 and the bin width. A function taking a sorted vector of breaks (bin edges) and returning an offset to subtract from the breaks. A string giving the suffix of a function that starts with "align_" used to determine the alignment, such as align_none(), align_boundary(), or align_center(). For example, align = "none" will provide no alignment, align = align_center(at = 0) will center a bin on 0, and align = align_boundary(at = 0) will align a bin edge on 0.
outline_bars	<scalar logical> Should outlines in between the bars (i.e. density values of 0) be included?
right_closed	<scalar logical> Should the right edge of each bin be closed? For a bin with endpoints $L$ and $U$: if TRUE, use $(L, U]$: the interval containing all $x$ such that $L < x \le U$. if FALSE, use $[L, U)$: the interval containing all $x$ such that $L \le x < U$. Equivalent to the right argument of hist() or the left.open argument of findInterval().
outermost_closed	<scalar logical> Should values on the edges of the outermost (first or last) bins always be included in those bins? If TRUE, the first edge (when right_closed = TRUE) or the last edge (when right_closed = FALSE) is treated as closed. Equivalent to the include.lowest argument of hist() or the rightmost.closed argument of findInterval().
na.rm	<scalar logical> Should missing (NA) values in x be removed?
...	Additional arguments (ignored).
range_only	<scalar logical> If TRUE, the range of the output of this density estimator is computed and is returned in the ⁠$x⁠ element of the result, and c(NA, NA) is returned in ⁠$y⁠. This gives a faster way to determine the range of the output than density_XXX(n = 2).

Value

An object of class "density", mimicking the output format of stats::density(), with the following components:

• x: The grid of points at which the density was estimated.

• y: The estimated density values.

• bw: The bandwidth.

• n: The sample size of the x input argument.

• call: The call used to produce the result, as a quoted expression.

• data.name: The deparsed name of the x input argument.

• has.na: Always FALSE (for compatibility).

• cdf: Values of the (possibly weighted) empirical cumulative distribution function at x. See weighted_ecdf().

This allows existing methods for density objects, like print() and plot(), to work if desired. This output format (and in particular, the x and y components) is also the format expected by the density argument of the stat_slabinterval() and the smooth_ family of functions.

See Also

Other density estimators: density_bounded(), density_unbounded()

Examples

library(distributional)
library(dplyr)
library(ggplot2)

# For compatibility with existing code, the return type of density_unbounded()
# is the same as stats::density(), ...
set.seed(123)
x = rbeta(5000, 1, 3)
d = density_histogram(x)
d

# ... thus, while designed for use with the `density` argument of
# stat_slabinterval(), output from density_histogram() can also be used with
# base::plot():
plot(d)

# here we'll use the same data as above with stat_slab():
data.frame(x) %>%
  ggplot() +
  stat_slab(
    aes(xdist = dist), data = data.frame(dist = dist_beta(1, 3)),
    alpha = 0.25
  ) +
  stat_slab(aes(x), density = "histogram", fill = NA, color = "#d95f02", alpha = 0.5) +
  scale_thickness_shared() +
  theme_ggdist()

---

Unbounded density estimator

Description

Unbounded density estimator using stats::density().

Supports automatic partial function application with waived arguments.

Usage

density_unbounded(
  x,
  weights = NULL,
  n = 501,
  bandwidth = "dpi",
  adjust = 1,
  kernel = "gaussian",
  trim = TRUE,
  adapt = 1,
  na.rm = FALSE,
  ...,
  range_only = FALSE
)

Arguments

x	<numeric> Sample to compute a density estimate for.
weights	<numeric | NULL> Optional weights to apply to x.
n	<scalar numeric> The number of grid points to evaluate the density estimator at.
bandwidth	<scalar numeric | function | string> Bandwidth of the density estimator. One of: a numeric: the bandwidth, as the standard deviation of the kernel a function: a function taking x (the sample) and returning the bandwidth a string: the suffix of the name of a function starting with "bandwidth_" that will be used to determine the bandwidth. See bandwidth for a list.
adjust	<scalar numeric> Value to multiply the bandwidth of the density estimator by. Default 1.
kernel	<string> The smoothing kernel to be used. This must partially match one of "gaussian", "rectangular", "triangular", "epanechnikov", "biweight", "cosine", or "optcosine". See stats::density().
trim	<scalar logical> Should the density estimate be trimmed to the range of the data? Default TRUE.
adapt	<positive integer> (very experimental) The name and interpretation of this argument are subject to change without notice. If adapt > 1, uses an adaptive approach to calculate the density. First, uses the adaptive bandwidth algorithm of Abramson (1982) to determine local (pointwise) bandwidths, then groups these bandwidths into adapt groups, then calculates and sums the densities from each group. You can set this to a very large number (e.g. Inf) for a fully adaptive approach, but this will be very slow; typically something around 100 yields nearly identical results.
na.rm	<scalar logical> Should missing (NA) values in x be removed?
...	Additional arguments (ignored).
range_only	<scalar logical> If TRUE, the range of the output of this density estimator is computed and is returned in the ⁠$x⁠ element of the result, and c(NA, NA) is returned in ⁠$y⁠. This gives a faster way to determine the range of the output than density_XXX(n = 2).

Value

An object of class "density", mimicking the output format of stats::density(), with the following components:

• x: The grid of points at which the density was estimated.

• y: The estimated density values.

• bw: The bandwidth.

• n: The sample size of the x input argument.

• call: The call used to produce the result, as a quoted expression.

• data.name: The deparsed name of the x input argument.

• has.na: Always FALSE (for compatibility).

• cdf: Values of the (possibly weighted) empirical cumulative distribution function at x. See weighted_ecdf().

This allows existing methods for density objects, like print() and plot(), to work if desired. This output format (and in particular, the x and y components) is also the format expected by the density argument of the stat_slabinterval() and the smooth_ family of functions.

See Also

Other density estimators: density_bounded(), density_histogram()

Examples

library(distributional)
library(dplyr)
library(ggplot2)

# For compatibility with existing code, the return type of density_unbounded()
# is the same as stats::density(), ...
set.seed(123)
x = rbeta(5000, 1, 3)
d = density_unbounded(x)
d

# ... thus, while designed for use with the `density` argument of
# stat_slabinterval(), output from density_unbounded() can also be used with
# base::plot():
plot(d)

# here we'll use the same data as above, but pick either density_bounded()
# or density_unbounded() (which is equivalent to stats::density()). Notice
# how the bounded density (green) is biased near the boundary of the support,
# while the unbounded density is not.
data.frame(x) %>%
  ggplot() +
  stat_slab(
    aes(xdist = dist), data = data.frame(dist = dist_beta(1, 3)),
    alpha = 0.25
  ) +
  stat_slab(aes(x), density = "bounded", fill = NA, color = "#d95f02", alpha = 0.5) +
  stat_slab(aes(x), density = "unbounded", fill = NA, color = "#1b9e77", alpha = 0.5) +
  scale_thickness_shared() +
  theme_ggdist()

---

Dynamically select a good bin width for a dotplot

Description

Searches for a nice-looking bin width to use to draw a dotplot such that the height of the dotplot fits within a given space (maxheight).

Usage

find_dotplot_binwidth(
  x,
  maxheight,
  heightratio = 1,
  stackratio = 1,
  layout = c("bin", "weave", "hex", "swarm", "bar")
)

Arguments

x	<numeric> Data values.
maxheight	<scalar numeric> Maximum height of the dotplot.
heightratio	<scalar numeric> Ratio of bin width to dot height.
stackratio	<scalar numeric> Ratio of dot height to vertical distance between dot centers
layout	<string> The layout method used for the dots. One of: "bin" (default): places dots on the off-axis at the midpoint of their bins as in the classic Wilkinson dotplot. This maintains the alignment of rows and columns in the dotplot. This layout is slightly different from the classic Wilkinson algorithm in that: (1) it nudges bins slightly to avoid overlapping bins and (2) if the input data are symmetrical it will return a symmetrical layout. "weave": uses the same basic binning approach of "bin", but places dots in the off-axis at their actual positions (unless overlaps = "nudge", in which case overlaps may be nudged out of the way). This maintains the alignment of rows but does not align dots within columns. "hex": uses the same basic binning approach of "bin", but alternates placing dots + binwidth/4 or - binwidth/4 in the off-axis from the bin center. This allows hexagonal packing by setting a stackratio less than 1 (something like 0.9 tends to work). "swarm": uses the "compactswarm" layout from beeswarm::beeswarm(). Does not maintain alignment of rows or columns, but can be more compact and neat looking, especially for sample data (as opposed to quantile dotplots of theoretical distributions, which may look better with "bin", "weave", or "hex"). "bar": for discrete distributions, lays out duplicate values in rectangular bars.

Details

This dynamic bin selection algorithm uses a binary search over the number of bins to find a bin width such that if the input data (x) is binned using a Wilkinson-style dotplot algorithm the height of the tallest bin will be less than maxheight.

This algorithm is used by geom_dotsinterval() (and its variants) to automatically select bin widths. Unless you are manually implementing you own dotplot grob or geom, you probably do not need to use this function directly

Value

A suitable bin width such that a dotplot created with this bin width and heightratio should have its tallest bin be less than or equal to maxheight.

See Also

bin_dots() for an algorithm can bin dots using bin widths selected by this function; geom_dotsinterval() for geometries that use these algorithms to create dotplots.

Examples

library(dplyr)
library(ggplot2)

x = qnorm(ppoints(20))
binwidth = find_dotplot_binwidth(x, maxheight = 4, heightratio = 1)
binwidth

bin_df = bin_dots(x = x, y = 0, binwidth = binwidth, heightratio = 1)
bin_df

# we can manually plot the binning above, though this is only recommended
# if you are using find_dotplot_binwidth() and bin_dots() to build your own
# grob. For practical use it is much easier to use geom_dots(), which will
# automatically select good bin widths for you (and which uses
# find_dotplot_binwidth() and bin_dots() internally)
bin_df %>%
  ggplot(aes(x = x, y = y)) +
  geom_point(size = 4) +
  coord_fixed()

---

Blurry dot plot (geom)

Description

Variant of geom_dots() for creating blurry dotplots. Accepts an sd aesthetic that gives the standard deviation of the blur applied to the dots. Requires a graphics engine supporting radial gradients. Unlike geom_dots(), this geom only supports circular and square shapes.

Usage

geom_blur_dots(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  blur = "gaussian",
  binwidth = NA,
  dotsize = 1.07,
  stackratio = 1,
  layout = "bin",
  overlaps = "nudge",
  smooth = "none",
  overflow = "warn",
  verbose = FALSE,
  orientation = NA,
  subguide = "slab",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  check.aes = TRUE,
  check.param = TRUE
)

Arguments

mapping	Set of aesthetic mappings created by aes(). If specified and inherit.aes = TRUE (the default), it is combined with the default mapping at the top level of the plot. You must supply mapping if there is no plot mapping.
data	The data to be displayed in this layer. There are three options: If NULL, the default, the data is inherited from the plot data as specified in the call to ggplot(). A data.frame, or other object, will override the plot data. All objects will be fortified to produce a data frame. See fortify() for which variables will be created. A function will be called with a single argument, the plot data. The return value must be a data.frame, and will be used as the layer data. A function can be created from a formula (e.g. ~ head(.x, 10)).
stat	The statistical transformation to use on the data for this layer. When using a ⁠geom_*()⁠ function to construct a layer, the stat argument can be used the override the default coupling between geoms and stats. The stat argument accepts the following: A Stat ggproto subclass, for example StatCount. A string naming the stat. To give the stat as a string, strip the function name of the stat_ prefix. For example, to use stat_count(), give the stat as "count". For more information and other ways to specify the stat, see the layer stat documentation.
position	<Position | string> Position adjustment, either as a string, or the result of a call to a position adjustment function. Setting this equal to "dodge" (position_dodge()) or "dodgejust" (position_dodgejust()) can be useful if you have overlapping geometries.
...	Other arguments passed to layer(). These are often aesthetics, used to set an aesthetic to a fixed value, like colour = "red" or linewidth = 3 (see Aesthetics, below). They may also be parameters to the paired geom/stat.
blur	<function | string> Blur function to apply to dots. One of: A function that takes a numeric vector of distances from the dot center, the dot radius, and the standard deviation of the blur and returns a vector of opacities in $[0, 1]$, such as blur_gaussian() or blur_interval(). A string indicating what blur function to use, as the suffix to a function name starting with blur_; e.g. "gaussian" (the default) applies blur_gaussian().
binwidth	<numeric | unit> The bin width to use for laying out the dots. One of: NA (the default): Dynamically select the bin width based on the size of the plot when drawn. This will pick a binwidth such that the tallest stack of dots is at most scale in height (ideally exactly scale in height, though this is not guaranteed). A length-1 (scalar) numeric or unit object giving the exact bin width. A length-2 (vector) numeric or unit object giving the minimum and maximum desired bin width. The bin width will be dynamically selected within these bounds. If the value is numeric, it is assumed to be in units of data. The bin width (or its bounds) can also be specified using unit(), which may be useful if it is desired that the dots be a certain point size or a certain percentage of the width/height of the viewport. For example, unit(0.1, "npc") would make dots that are exactly 10% of the viewport size along whichever dimension the dotplot is drawn; unit(c(0, 0.1), "npc") would make dots that are at most 10% of the viewport size (while still ensuring the tallest stack is less than or equal to scale).
dotsize	<scalar numeric> The width of the dots relative to the binwidth. The default, 1.07, makes dots be just a bit wider than the bin width, which is a manually-tuned parameter that tends to work well with the default circular shape, preventing gaps between bins from appearing to be too large visually (as might arise from dots being precisely the binwidth). If it is desired to have dots be precisely the binwidth, set dotsize = 1.
stackratio	<scalar numeric> The distance between the center of the dots in the same stack relative to the dot height. The default, 1, makes dots in the same stack just touch each other.
layout	<string> The layout method used for the dots. One of: "bin" (default): places dots on the off-axis at the midpoint of their bins as in the classic Wilkinson dotplot. This maintains the alignment of rows and columns in the dotplot. This layout is slightly different from the classic Wilkinson algorithm in that: (1) it nudges bins slightly to avoid overlapping bins and (2) if the input data are symmetrical it will return a symmetrical layout. "weave": uses the same basic binning approach of "bin", but places dots in the off-axis at their actual positions (unless overlaps = "nudge", in which case overlaps may be nudged out of the way). This maintains the alignment of rows but does not align dots within columns. "hex": uses the same basic binning approach of "bin", but alternates placing dots + binwidth/4 or - binwidth/4 in the off-axis from the bin center. This allows hexagonal packing by setting a stackratio less than 1 (something like 0.9 tends to work). "swarm": uses the "compactswarm" layout from beeswarm::beeswarm(). Does not maintain alignment of rows or columns, but can be more compact and neat looking, especially for sample data (as opposed to quantile dotplots of theoretical distributions, which may look better with "bin", "weave", or "hex"). "bar": for discrete distributions, lays out duplicate values in rectangular bars.
overlaps	<string> How to handle overlapping dots or bins in the "bin", "weave", and "hex" layouts (dots never overlap in the "swarm" or "bar" layouts). For the purposes of this argument, dots are only considered to be overlapping if they would be overlapping when dotsize = 1 and stackratio = 1; i.e. if you set those arguments to other values, overlaps may still occur. One of: "keep": leave overlapping dots as they are. Dots may overlap (usually only slightly) in the "bin", "weave", and "hex" layouts. "nudge": nudge overlapping dots out of the way. Overlaps are avoided using a constrained optimization which minimizes the squared distance of dots to their desired positions, subject to the constraint that adjacent dots do not overlap.
smooth	<function | string> Smoother to apply to dot positions. One of: A function that takes a numeric vector of dot positions and returns a smoothed version of that vector, such as smooth_bounded(), smooth_unbounded(), smooth_discrete()⁠, or ⁠smooth_bar()'. A string indicating what smoother to use, as the suffix to a function name starting with smooth_; e.g. "none" (the default) applies smooth_none(), which simply returns the given vector without applying smoothing. Smoothing is most effective when the smoother is matched to the support of the distribution; e.g. using smooth_bounded(bounds = ...).
overflow	<string> How to handle overflow of dots beyond the extent of the geom when a minimum binwidth (or an exact binwidth) is supplied. One of: "keep": Keep the overflow, drawing dots outside the geom bounds. "warn": Keep the overflow, but produce a warning suggesting solutions, such as setting binwidth = NA or overflow = "compress". "compress": Compress the layout. Reduces the binwidth to the size necessary to keep the dots within bounds, then adjusts stackratio and dotsize so that the apparent dot size is the user-specified minimum binwidth times the user-specified dotsize. If you find the default layout has dots that are too small, and you are okay with dots overlapping, consider setting overflow = "compress" and supplying an exact or minimum dot size using binwidth.
verbose	<scalar logical> If TRUE, print out the bin width of the dotplot. Can be useful if you want to start from an automatically-selected bin width and then adjust it manually. Bin width is printed both as data units and as normalized parent coordinates or "npc"s (see unit()). Note that if you just want to scale the selected bin width to fit within a desired area, it is probably easier to use scale than to copy and scale binwidth manually, and if you just want to provide constraints on the bin width, you can pass a length-2 vector to binwidth.
orientation	<string> Whether this geom is drawn horizontally or vertically. One of: NA (default): automatically detect the orientation based on how the aesthetics are assigned. Automatic detection works most of the time. "horizontal" (or "y"): draw horizontally, using the y aesthetic to identify different groups. For each group, uses the x, xmin, xmax, and thickness aesthetics to draw points, intervals, and slabs. "vertical" (or "x"): draw vertically, using the x aesthetic to identify different groups. For each group, uses the y, ymin, ymax, and thickness aesthetics to draw points, intervals, and slabs. For compatibility with the base ggplot naming scheme for orientation, "x" can be used as an alias for "vertical" and "y" as an alias for "horizontal" (ggdist had an orientation parameter before base ggplot did, hence the discrepancy).
subguide	<function | string> Sub-guide used to annotate the thickness scale. One of: A function that takes a scale argument giving a ggplot2::Scale object and an orientation argument giving the orientation of the geometry and then returns a grid::grob that will draw the axis annotation, such as subguide_axis() (to draw a traditional axis) or subguide_none() (to draw no annotation). See subguide_axis() for a list of possibilities and examples. A string giving the name of such a function when prefixed with "subguide_"; e.g. "axis" or "none". The values "slab", "dots", and "spike" use the default subguide for their geom families (no subguide), which can be modified by setting subguide_slab, subguide_dots, or subguide_spike; see the documentation for those functions.
na.rm	<scalar logical> If FALSE, the default, missing values are removed with a warning. If TRUE, missing values are silently removed.
show.legend	logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes. It can also be a named logical vector to finely select the aesthetics to display.
inherit.aes	If FALSE, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. borders().
check.aes, check.param	If TRUE, the default, will check that supplied parameters and aesthetics are understood by the geom or stat. Use FALSE to suppress the checks.

Details

The dots family of stats and geoms are similar to ggplot2::geom_dotplot() but with a number of differences:

• Dots geoms act like slabs in geom_slabinterval() and can be given x positions (or y positions when in a horizontal orientation).

• Given the available space to lay out dots, the dots geoms will automatically determine how many bins to use to fit the available space.

• Dots geoms use a dynamic layout algorithm that lays out dots from the center out if the input data are symmetrical, guaranteeing that symmetrical data results in a symmetrical plot. The layout algorithm also prevents dots from overlapping each other.

• The shape of the dots in these geoms can be changed using the slab_shape aesthetic (when using the dotsinterval family) or the shape or slab_shape aesthetic (when using the dots family)

Stats and geoms in this family include:

• geom_dots(): dotplots on raw data. Ensures the dotplot fits within available space by reducing the size of the dots automatically (may result in very small dots).

• geom_swarm() and geom_weave(): dotplots on raw data with defaults intended to create "beeswarm" plots. Used side = "both" by default, and sets the default dot size to the same size as geom_point() (binwidth = unit(1.5, "mm")), allowing dots to overlap instead of getting very small.

• stat_dots(): dotplots on raw data, distributional objects, and posterior::rvar()s

• geom_dotsinterval(): dotplot + interval plots on raw data with already-calculated intervals (rarely useful directly).

• stat_dotsinterval(): dotplot + interval plots on raw data, distributional objects, and posterior::rvar()s (will calculate intervals for you).

• geom_blur_dots(): blurry dotplots that allow the standard deviation of a blur applied to each dot to be specified using the sd aesthetic.

• stat_mcse_dots(): blurry dotplots of quantiles using the Monte Carlo Standard Error of each quantile.

stat_dots() and stat_dotsinterval(), when used with the quantiles argument, are particularly useful for constructing quantile dotplots, which can be an effective way to communicate uncertainty using a frequency framing that may be easier for laypeople to understand (Kay et al. 2016, Fernandes et al. 2018).

Value

A ggplot2::Geom representing a blurry dot geometry which can be added to a ggplot() object.

Aesthetics

The dots+interval stats and geoms have a wide variety of aesthetics that control the appearance of their three sub-geometries: the dots (aka the slab), the point, and the interval.

Positional aesthetics

• x: x position of the geometry

• y: y position of the geometry

Dots-specific (aka Slab-specific) aesthetics

• sd: The standard deviation (in data units) of the blur associated with each dot.

• order: The order in which data points are stacked within bins. Can be used to create the effect of "stacked" dots by ordering dots according to a discrete variable. If omitted (NULL), the value of the data points themselves are used to determine stacking order. Only applies when layout is "bin" or "hex", as the other layout methods fully determine both x and y positions.

• side: Which side to place the slab on. "topright", "top", and "right" are synonyms which cause the slab to be drawn on the top or the right depending on if orientation is "horizontal" or "vertical". "bottomleft", "bottom", and "left" are synonyms which cause the slab to be drawn on the bottom or the left depending on if orientation is "horizontal" or "vertical". "topleft" causes the slab to be drawn on the top or the left, and "bottomright" causes the slab to be drawn on the bottom or the right. "both" draws the slab mirrored on both sides (as in a violin plot).

• scale: What proportion of the region allocated to this geom to use to draw the slab. If scale = 1, slabs that use the maximum range will just touch each other. Default is 0.9 to leave some space between adjacent slabs. For a comprehensive discussion and examples of slab scaling and normalization, see the thickness scale article.

• justification: Justification of the interval relative to the slab, where 0 indicates bottom/left justification and 1 indicates top/right justification (depending on orientation). If justification is NULL (the default), then it is set automatically based on the value of side: when side is "top"/"right" justification is set to 0, when side is "bottom"/"left" justification is set to 1, and when side is "both" justification is set to 0.5.

• datatype: When using composite geoms directly without a stat (e.g. geom_slabinterval()), datatype is used to indicate which part of the geom a row in the data targets: rows with datatype = "slab" target the slab portion of the geometry and rows with datatype = "interval" target the interval portion of the geometry. This is set automatically when using ggdist stats.

Interval-specific aesthetics

• xmin: Left end of the interval sub-geometry (if orientation = "horizontal").

• xmax: Right end of the interval sub-geometry (if orientation = "horizontal").

• ymin: Lower end of the interval sub-geometry (if orientation = "vertical").

• ymax: Upper end of the interval sub-geometry (if orientation = "vertical").

Point-specific aesthetics

• shape: Shape type used to draw the point sub-geometry.

Color aesthetics

• colour: (or color) The color of the interval and point sub-geometries. Use the slab_color, interval_color, or point_color aesthetics (below) to set sub-geometry colors separately.

• fill: The fill color of the slab and point sub-geometries. Use the slab_fill or point_fill aesthetics (below) to set sub-geometry colors separately.

• alpha: The opacity of the slab, interval, and point sub-geometries. Use the slab_alpha, interval_alpha, or point_alpha aesthetics (below) to set sub-geometry colors separately.

• colour_ramp: (or color_ramp) A secondary scale that modifies the color scale to "ramp" to another color. See scale_colour_ramp() for examples.

• fill_ramp: A secondary scale that modifies the fill scale to "ramp" to another color. See scale_fill_ramp() for examples.

Line aesthetics

• linewidth: Width of the line used to draw the interval (except with geom_slab(): then it is the width of the slab). With composite geometries including an interval and slab, use slab_linewidth to set the line width of the slab (see below). For interval, raw linewidth values are transformed according to the interval_size_domain and interval_size_range parameters of the geom (see above).

• size: Determines the size of the point. If linewidth is not provided, size will also determines the width of the line used to draw the interval (this allows line width and point size to be modified together by setting only size and not linewidth). Raw size values are transformed according to the interval_size_domain, interval_size_range, and fatten_point parameters of the geom (see above). Use the point_size aesthetic (below) to set sub-geometry size directly without applying the effects of interval_size_domain, interval_size_range, and fatten_point.

• stroke: Width of the outline around the point sub-geometry.

• linetype: Type of line (e.g., "solid", "dashed", etc) used to draw the interval and the outline of the slab (if it is visible). Use the slab_linetype or interval_linetype aesthetics (below) to set sub-geometry line types separately.

Slab-specific color and line override aesthetics

• slab_fill: Override for fill: the fill color of the slab.

• slab_colour: (or slab_color) Override for colour/color: the outline color of the slab.

• slab_alpha: Override for alpha: the opacity of the slab.

• slab_linewidth: Override for linwidth: the width of the outline of the slab.

• slab_linetype: Override for linetype: the line type of the outline of the slab.

• slab_shape: Override for shape: the shape of the dots used to draw the dotplot slab.

Interval-specific color and line override aesthetics

• interval_colour: (or interval_color) Override for colour/color: the color of the interval.

• interval_alpha: Override for alpha: the opacity of the interval.

• interval_linetype: Override for linetype: the line type of the interval.

Point-specific color and line override aesthetics

• point_fill: Override for fill: the fill color of the point.

• point_colour: (or point_color) Override for colour/color: the outline color of the point.

• point_alpha: Override for alpha: the opacity of the point.

• point_size: Override for size: the size of the point.

Deprecated aesthetics

• slab_size: Use slab_linewidth.

• interval_size: Use interval_linewidth.

Other aesthetics (these work as in standard geoms)

• width

• height

• group

See examples of some of these aesthetics in action in vignette("dotsinterval"). Learn more about the sub-geom override aesthetics (like interval_color) in the scales documentation. Learn more about basic ggplot aesthetics in vignette("ggplot2-specs").

References

Kay, M., Kola, T., Hullman, J. R., & Munson, S. A. (2016). When (ish) is My Bus? User-centered Visualizations of Uncertainty in Everyday, Mobile Predictive Systems. Conference on Human Factors in Computing Systems - CHI '16, 5092–5103. doi:10.1145/2858036.2858558.

Fernandes, M., Walls, L., Munson, S., Hullman, J., & Kay, M. (2018). Uncertainty Displays Using Quantile Dotplots or CDFs Improve Transit Decision-Making. Conference on Human Factors in Computing Systems - CHI '18. doi:10.1145/3173574.3173718.

See Also

See geom_dotsinterval() for the geometry this shortcut is based on.

See vignette("dotsinterval") for a variety of examples of use.

Other dotsinterval geoms: geom_dots(), geom_dotsinterval(), geom_swarm(), geom_weave()

Examples

library(dplyr)
library(ggplot2)

theme_set(theme_ggdist())

set.seed(1234)
x = rnorm(1000)

# manually calculate quantiles and their MCSE
# this could also be done more succinctly with stat_mcse_dots()
p = ppoints(100)
df = data.frame(
  q = quantile(x, p),
  se = posterior::mcse_quantile(x, p)
)

df %>%
  ggplot(aes(x = q, sd = se)) +
  geom_blur_dots()

df %>%
  ggplot(aes(x = q, sd = se)) +
  # or blur = blur_interval(.width = .95) to set the interval width
  geom_blur_dots(blur = "interval")

---

Dot plot (shortcut geom)

Description

Shortcut version of geom_dotsinterval() for creating dot plots. Geoms based on geom_dotsinterval() create dotplots that automatically ensure the plot fits within the available space.

Roughly equivalent to:

geom_dotsinterval(
  show_point = FALSE,
  show_interval = FALSE
)

Usage

geom_dots(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  binwidth = NA,
  dotsize = 1.07,
  stackratio = 1,
  layout = "bin",
  overlaps = "nudge",
  smooth = "none",
  overflow = "warn",
  verbose = FALSE,
  orientation = NA,
  subguide = "slab",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  check.aes = TRUE,
  check.param = TRUE
)

Arguments

mapping	Set of aesthetic mappings created by aes(). If specified and inherit.aes = TRUE (the default), it is combined with the default mapping at the top level of the plot. You must supply mapping if there is no plot mapping.
data	The data to be displayed in this layer. There are three options: If NULL, the default, the data is inherited from the plot data as specified in the call to ggplot(). A data.frame, or other object, will override the plot data. All objects will be fortified to produce a data frame. See fortify() for which variables will be created. A function will be called with a single argument, the plot data. The return value must be a data.frame, and will be used as the layer data. A function can be created from a formula (e.g. ~ head(.x, 10)).
stat	The statistical transformation to use on the data for this layer. When using a ⁠geom_*()⁠ function to construct a layer, the stat argument can be used the override the default coupling between geoms and stats. The stat argument accepts the following: A Stat ggproto subclass, for example StatCount. A string naming the stat. To give the stat as a string, strip the function name of the stat_ prefix. For example, to use stat_count(), give the stat as "count". For more information and other ways to specify the stat, see the layer stat documentation.
position	<Position | string> Position adjustment, either as a string, or the result of a call to a position adjustment function. Setting this equal to "dodge" (position_dodge()) or "dodgejust" (position_dodgejust()) can be useful if you have overlapping geometries.
...	Other arguments passed to layer(). These are often aesthetics, used to set an aesthetic to a fixed value, like colour = "red" or linewidth = 3 (see Aesthetics, below). They may also be parameters to the paired geom/stat.
binwidth	<numeric | unit> The bin width to use for laying out the dots. One of: NA (the default): Dynamically select the bin width based on the size of the plot when drawn. This will pick a binwidth such that the tallest stack of dots is at most scale in height (ideally exactly scale in height, though this is not guaranteed). A length-1 (scalar) numeric or unit object giving the exact bin width. A length-2 (vector) numeric or unit object giving the minimum and maximum desired bin width. The bin width will be dynamically selected within these bounds. If the value is numeric, it is assumed to be in units of data. The bin width (or its bounds) can also be specified using unit(), which may be useful if it is desired that the dots be a certain point size or a certain percentage of the width/height of the viewport. For example, unit(0.1, "npc") would make dots that are exactly 10% of the viewport size along whichever dimension the dotplot is drawn; unit(c(0, 0.1), "npc") would make dots that are at most 10% of the viewport size (while still ensuring the tallest stack is less than or equal to scale).
dotsize	<scalar numeric> The width of the dots relative to the binwidth. The default, 1.07, makes dots be just a bit wider than the bin width, which is a manually-tuned parameter that tends to work well with the default circular shape, preventing gaps between bins from appearing to be too large visually (as might arise from dots being precisely the binwidth). If it is desired to have dots be precisely the binwidth, set dotsize = 1.
stackratio	<scalar numeric> The distance between the center of the dots in the same stack relative to the dot height. The default, 1, makes dots in the same stack just touch each other.
layout	<string> The layout method used for the dots. One of: "bin" (default): places dots on the off-axis at the midpoint of their bins as in the classic Wilkinson dotplot. This maintains the alignment of rows and columns in the dotplot. This layout is slightly different from the classic Wilkinson algorithm in that: (1) it nudges bins slightly to avoid overlapping bins and (2) if the input data are symmetrical it will return a symmetrical layout. "weave": uses the same basic binning approach of "bin", but places dots in the off-axis at their actual positions (unless overlaps = "nudge", in which case overlaps may be nudged out of the way). This maintains the alignment of rows but does not align dots within columns. "hex": uses the same basic binning approach of "bin", but alternates placing dots + binwidth/4 or - binwidth/4 in the off-axis from the bin center. This allows hexagonal packing by setting a stackratio less than 1 (something like 0.9 tends to work). "swarm": uses the "compactswarm" layout from beeswarm::beeswarm(). Does not maintain alignment of rows or columns, but can be more compact and neat looking, especially for sample data (as opposed to quantile dotplots of theoretical distributions, which may look better with "bin", "weave", or "hex"). "bar": for discrete distributions, lays out duplicate values in rectangular bars.
overlaps	<string> How to handle overlapping dots or bins in the "bin", "weave", and "hex" layouts (dots never overlap in the "swarm" or "bar" layouts). For the purposes of this argument, dots are only considered to be overlapping if they would be overlapping when dotsize = 1 and stackratio = 1; i.e. if you set those arguments to other values, overlaps may still occur. One of: "keep": leave overlapping dots as they are. Dots may overlap (usually only slightly) in the "bin", "weave", and "hex" layouts. "nudge": nudge overlapping dots out of the way. Overlaps are avoided using a constrained optimization which minimizes the squared distance of dots to their desired positions, subject to the constraint that adjacent dots do not overlap.
smooth	<function | string> Smoother to apply to dot positions. One of: A function that takes a numeric vector of dot positions and returns a smoothed version of that vector, such as smooth_bounded(), smooth_unbounded(), smooth_discrete()⁠, or ⁠smooth_bar()'. A string indicating what smoother to use, as the suffix to a function name starting with smooth_; e.g. "none" (the default) applies smooth_none(), which simply returns the given vector without applying smoothing. Smoothing is most effective when the smoother is matched to the support of the distribution; e.g. using smooth_bounded(bounds = ...).
overflow	<string> How to handle overflow of dots beyond the extent of the geom when a minimum binwidth (or an exact binwidth) is supplied. One of: "keep": Keep the overflow, drawing dots outside the geom bounds. "warn": Keep the overflow, but produce a warning suggesting solutions, such as setting binwidth = NA or overflow = "compress". "compress": Compress the layout. Reduces the binwidth to the size necessary to keep the dots within bounds, then adjusts stackratio and dotsize so that the apparent dot size is the user-specified minimum binwidth times the user-specified dotsize. If you find the default layout has dots that are too small, and you are okay with dots overlapping, consider setting overflow = "compress" and supplying an exact or minimum dot size using binwidth.
verbose	<scalar logical> If TRUE, print out the bin width of the dotplot. Can be useful if you want to start from an automatically-selected bin width and then adjust it manually. Bin width is printed both as data units and as normalized parent coordinates or "npc"s (see unit()). Note that if you just want to scale the selected bin width to fit within a desired area, it is probably easier to use scale than to copy and scale binwidth manually, and if you just want to provide constraints on the bin width, you can pass a length-2 vector to binwidth.
orientation	<string> Whether this geom is drawn horizontally or vertically. One of: NA (default): automatically detect the orientation based on how the aesthetics are assigned. Automatic detection works most of the time. "horizontal" (or "y"): draw horizontally, using the y aesthetic to identify different groups. For each group, uses the x, xmin, xmax, and thickness aesthetics to draw points, intervals, and slabs. "vertical" (or "x"): draw vertically, using the x aesthetic to identify different groups. For each group, uses the y, ymin, ymax, and thickness aesthetics to draw points, intervals, and slabs. For compatibility with the base ggplot naming scheme for orientation, "x" can be used as an alias for "vertical" and "y" as an alias for "horizontal" (ggdist had an orientation parameter before base ggplot did, hence the discrepancy).
subguide	<function | string> Sub-guide used to annotate the thickness scale. One of: A function that takes a scale argument giving a ggplot2::Scale object and an orientation argument giving the orientation of the geometry and then returns a grid::grob that will draw the axis annotation, such as subguide_axis() (to draw a traditional axis) or subguide_none() (to draw no annotation). See subguide_axis() for a list of possibilities and examples. A string giving the name of such a function when prefixed with "subguide_"; e.g. "axis" or "none". The values "slab", "dots", and "spike" use the default subguide for their geom families (no subguide), which can be modified by setting subguide_slab, subguide_dots, or subguide_spike; see the documentation for those functions.
na.rm	<scalar logical> If FALSE, the default, missing values are removed with a warning. If TRUE, missing values are silently removed.
show.legend	logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes. It can also be a named logical vector to finely select the aesthetics to display.
inherit.aes	If FALSE, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. borders().
check.aes, check.param	If TRUE, the default, will check that supplied parameters and aesthetics are understood by the geom or stat. Use FALSE to suppress the checks.

Details

The dots family of stats and geoms are similar to ggplot2::geom_dotplot() but with a number of differences:

• Dots geoms act like slabs in geom_slabinterval() and can be given x positions (or y positions when in a horizontal orientation).

• Given the available space to lay out dots, the dots geoms will automatically determine how many bins to use to fit the available space.

• Dots geoms use a dynamic layout algorithm that lays out dots from the center out if the input data are symmetrical, guaranteeing that symmetrical data results in a symmetrical plot. The layout algorithm also prevents dots from overlapping each other.

• The shape of the dots in these geoms can be changed using the slab_shape aesthetic (when using the dotsinterval family) or the shape or slab_shape aesthetic (when using the dots family)

Stats and geoms in this family include:

• geom_dots(): dotplots on raw data. Ensures the dotplot fits within available space by reducing the size of the dots automatically (may result in very small dots).

• geom_swarm() and geom_weave(): dotplots on raw data with defaults intended to create "beeswarm" plots. Used side = "both" by default, and sets the default dot size to the same size as geom_point() (binwidth = unit(1.5, "mm")), allowing dots to overlap instead of getting very small.

• stat_dots(): dotplots on raw data, distributional objects, and posterior::rvar()s

• geom_dotsinterval(): dotplot + interval plots on raw data with already-calculated intervals (rarely useful directly).

• stat_dotsinterval(): dotplot + interval plots on raw data, distributional objects, and posterior::rvar()s (will calculate intervals for you).

• geom_blur_dots(): blurry dotplots that allow the standard deviation of a blur applied to each dot to be specified using the sd aesthetic.

• stat_mcse_dots(): blurry dotplots of quantiles using the Monte Carlo Standard Error of each quantile.

stat_dots() and stat_dotsinterval(), when used with the quantiles argument, are particularly useful for constructing quantile dotplots, which can be an effective way to communicate uncertainty using a frequency framing that may be easier for laypeople to understand (Kay et al. 2016, Fernandes et al. 2018).

Value

A ggplot2::Geom representing a dot geometry which can be added to a ggplot() object.

Aesthetics

The dots+interval stats and geoms have a wide variety of aesthetics that control the appearance of their three sub-geometries: the dots (aka the slab), the point, and the interval.

Positional aesthetics

• x: x position of the geometry

• y: y position of the geometry

Dots-specific (aka Slab-specific) aesthetics

• family: The font family used to draw the dots.

• order: The order in which data points are stacked within bins. Can be used to create the effect of "stacked" dots by ordering dots according to a discrete variable. If omitted (NULL), the value of the data points themselves are used to determine stacking order. Only applies when layout is "bin" or "hex", as the other layout methods fully determine both x and y positions.

• side: Which side to place the slab on. "topright", "top", and "right" are synonyms which cause the slab to be drawn on the top or the right depending on if orientation is "horizontal" or "vertical". "bottomleft", "bottom", and "left" are synonyms which cause the slab to be drawn on the bottom or the left depending on if orientation is "horizontal" or "vertical". "topleft" causes the slab to be drawn on the top or the left, and "bottomright" causes the slab to be drawn on the bottom or the right. "both" draws the slab mirrored on both sides (as in a violin plot).

• scale: What proportion of the region allocated to this geom to use to draw the slab. If scale = 1, slabs that use the maximum range will just touch each other. Default is 0.9 to leave some space between adjacent slabs. For a comprehensive discussion and examples of slab scaling and normalization, see the thickness scale article.

• justification: Justification of the interval relative to the slab, where 0 indicates bottom/left justification and 1 indicates top/right justification (depending on orientation). If justification is NULL (the default), then it is set automatically based on the value of side: when side is "top"/"right" justification is set to 0, when side is "bottom"/"left" justification is set to 1, and when side is "both" justification is set to 0.5.

• datatype: When using composite geoms directly without a stat (e.g. geom_slabinterval()), datatype is used to indicate which part of the geom a row in the data targets: rows with datatype = "slab" target the slab portion of the geometry and rows with datatype = "interval" target the interval portion of the geometry. This is set automatically when using ggdist stats.

Interval-specific aesthetics

• xmin: Left end of the interval sub-geometry (if orientation = "horizontal").

• xmax: Right end of the interval sub-geometry (if orientation = "horizontal").

• ymin: Lower end of the interval sub-geometry (if orientation = "vertical").

• ymax: Upper end of the interval sub-geometry (if orientation = "vertical").

Point-specific aesthetics

• shape: Shape type used to draw the point sub-geometry.

Color aesthetics

• colour: (or color) The color of the interval and point sub-geometries. Use the slab_color, interval_color, or point_color aesthetics (below) to set sub-geometry colors separately.

• fill: The fill color of the slab and point sub-geometries. Use the slab_fill or point_fill aesthetics (below) to set sub-geometry colors separately.

• alpha: The opacity of the slab, interval, and point sub-geometries. Use the slab_alpha, interval_alpha, or point_alpha aesthetics (below) to set sub-geometry colors separately.

• colour_ramp: (or color_ramp) A secondary scale that modifies the color scale to "ramp" to another color. See scale_colour_ramp() for examples.

• fill_ramp: A secondary scale that modifies the fill scale to "ramp" to another color. See scale_fill_ramp() for examples.

Line aesthetics

• linewidth: Width of the line used to draw the interval (except with geom_slab(): then it is the width of the slab). With composite geometries including an interval and slab, use slab_linewidth to set the line width of the slab (see below). For interval, raw linewidth values are transformed according to the interval_size_domain and interval_size_range parameters of the geom (see above).

• size: Determines the size of the point. If linewidth is not provided, size will also determines the width of the line used to draw the interval (this allows line width and point size to be modified together by setting only size and not linewidth). Raw size values are transformed according to the interval_size_domain, interval_size_range, and fatten_point parameters of the geom (see above). Use the point_size aesthetic (below) to set sub-geometry size directly without applying the effects of interval_size_domain, interval_size_range, and fatten_point.

• stroke: Width of the outline around the point sub-geometry.

• linetype: Type of line (e.g., "solid", "dashed", etc) used to draw the interval and the outline of the slab (if it is visible). Use the slab_linetype or interval_linetype aesthetics (below) to set sub-geometry line types separately.

Slab-specific color and line override aesthetics

• slab_fill: Override for fill: the fill color of the slab.

• slab_colour: (or slab_color) Override for colour/color: the outline color of the slab.

• slab_alpha: Override for alpha: the opacity of the slab.

• slab_linewidth: Override for linwidth: the width of the outline of the slab.

• slab_linetype: Override for linetype: the line type of the outline of the slab.

• slab_shape: Override for shape: the shape of the dots used to draw the dotplot slab.

Interval-specific color and line override aesthetics

• interval_colour: (or interval_color) Override for colour/color: the color of the interval.

• interval_alpha: Override for alpha: the opacity of the interval.

• interval_linetype: Override for linetype: the line type of the interval.

Point-specific color and line override aesthetics

• point_fill: Override for fill: the fill color of the point.

• point_colour: (or point_color) Override for colour/color: the outline color of the point.

• point_alpha: Override for alpha: the opacity of the point.

• point_size: Override for size: the size of the point.

Deprecated aesthetics

• slab_size: Use slab_linewidth.

• interval_size: Use interval_linewidth.

Other aesthetics (these work as in standard geoms)

• width

• height

• group

See examples of some of these aesthetics in action in vignette("dotsinterval"). Learn more about the sub-geom override aesthetics (like interval_color) in the scales documentation. Learn more about basic ggplot aesthetics in vignette("ggplot2-specs").

References

Kay, M., Kola, T., Hullman, J. R., & Munson, S. A. (2016). When (ish) is My Bus? User-centered Visualizations of Uncertainty in Everyday, Mobile Predictive Systems. Conference on Human Factors in Computing Systems - CHI '16, 5092–5103. doi:10.1145/2858036.2858558.

Fernandes, M., Walls, L., Munson, S., Hullman, J., & Kay, M. (2018). Uncertainty Displays Using Quantile Dotplots or CDFs Improve Transit Decision-Making. Conference on Human Factors in Computing Systems - CHI '18. doi:10.1145/3173574.3173718.

See Also

See stat_dots() for the stat version, intended for use on sample data or analytical distributions.

See geom_dotsinterval() for the geometry this shortcut is based on.

See vignette("dotsinterval") for a variety of examples of use.

Other dotsinterval geoms: geom_blur_dots(), geom_dotsinterval(), geom_swarm(), geom_weave()

Examples

library(dplyr)
library(ggplot2)

theme_set(theme_ggdist())

set.seed(12345)
df = tibble(
  g = rep(c("a", "b"), 200),
  value = rnorm(400, c(0, 3), c(0.75, 1))
)

# orientation is detected automatically based on
# which axis is discrete

df %>%
  ggplot(aes(x = value, y = g)) +
  geom_dots()

df %>%
  ggplot(aes(y = value, x = g)) +
  geom_dots()

---

Automatic dotplot + point + interval meta-geom

Description

This meta-geom supports drawing combinations of dotplots, points, and intervals. Geoms and stats based on geom_dotsinterval() create dotplots that automatically determine a bin width that ensures the plot fits within the available space. They also ensure dots do not overlap, and allow the generation of quantile dotplots using the quantiles argument to stat_dotsinterval()/stat_dots(). Generally follows the naming scheme and arguments of the geom_slabinterval() and stat_slabinterval() family of geoms and stats.

Usage

geom_dotsinterval(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  binwidth = NA,
  dotsize = 1.07,
  stackratio = 1,
  layout = "bin",
  overlaps = "nudge",
  smooth = "none",
  overflow = "warn",
  verbose = FALSE,
  orientation = NA,
  interval_size_domain = c(1, 6),
  interval_size_range = c(0.6, 1.4),
  fatten_point = 1.8,
  arrow = NULL,
  show_slab = TRUE,
  show_point = TRUE,
  show_interval = TRUE,
  subguide = "slab",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  check.aes = TRUE,
  check.param = TRUE
)

Arguments

mapping	Set of aesthetic mappings created by aes(). If specified and inherit.aes = TRUE (the default), it is combined with the default mapping at the top level of the plot. You must supply mapping if there is no plot mapping.
data	The data to be displayed in this layer. There are three options: If NULL, the default, the data is inherited from the plot data as specified in the call to ggplot(). A data.frame, or other object, will override the plot data. All objects will be fortified to produce a data frame. See fortify() for which variables will be created. A function will be called with a single argument, the plot data. The return value must be a data.frame, and will be used as the layer data. A function can be created from a formula (e.g. ~ head(.x, 10)).
stat	The statistical transformation to use on the data for this layer. When using a ⁠geom_*()⁠ function to construct a layer, the stat argument can be used the override the default coupling between geoms and stats. The stat argument accepts the following: A Stat ggproto subclass, for example StatCount. A string naming the stat. To give the stat as a string, strip the function name of the stat_ prefix. For example, to use stat_count(), give the stat as "count". For more information and other ways to specify the stat, see the layer stat documentation.
position	<Position | string> Position adjustment, either as a string, or the result of a call to a position adjustment function. Setting this equal to "dodge" (position_dodge()) or "dodgejust" (position_dodgejust()) can be useful if you have overlapping geometries.
...	Other arguments passed to layer(). These are often aesthetics, used to set an aesthetic to a fixed value, like colour = "red" or linewidth = 3 (see Aesthetics, below). They may also be parameters to the paired geom/stat.
binwidth	<numeric | unit> The bin width to use for laying out the dots. One of: NA (the default): Dynamically select the bin width based on the size of the plot when drawn. This will pick a binwidth such that the tallest stack of dots is at most scale in height (ideally exactly scale in height, though this is not guaranteed). A length-1 (scalar) numeric or unit object giving the exact bin width. A length-2 (vector) numeric or unit object giving the minimum and maximum desired bin width. The bin width will be dynamically selected within these bounds. If the value is numeric, it is assumed to be in units of data. The bin width (or its bounds) can also be specified using unit(), which may be useful if it is desired that the dots be a certain point size or a certain percentage of the width/height of the viewport. For example, unit(0.1, "npc") would make dots that are exactly 10% of the viewport size along whichever dimension the dotplot is drawn; unit(c(0, 0.1), "npc") would make dots that are at most 10% of the viewport size (while still ensuring the tallest stack is less than or equal to scale).
dotsize	<scalar numeric> The width of the dots relative to the binwidth. The default, 1.07, makes dots be just a bit wider than the bin width, which is a manually-tuned parameter that tends to work well with the default circular shape, preventing gaps between bins from appearing to be too large visually (as might arise from dots being precisely the binwidth). If it is desired to have dots be precisely the binwidth, set dotsize = 1.
stackratio	<scalar numeric> The distance between the center of the dots in the same stack relative to the dot height. The default, 1, makes dots in the same stack just touch each other.
layout	<string> The layout method used for the dots. One of: "bin" (default): places dots on the off-axis at the midpoint of their bins as in the classic Wilkinson dotplot. This maintains the alignment of rows and columns in the dotplot. This layout is slightly different from the classic Wilkinson algorithm in that: (1) it nudges bins slightly to avoid overlapping bins and (2) if the input data are symmetrical it will return a symmetrical layout. "weave": uses the same basic binning approach of "bin", but places dots in the off-axis at their actual positions (unless overlaps = "nudge", in which case overlaps may be nudged out of the way). This maintains the alignment of rows but does not align dots within columns. "hex": uses the same basic binning approach of "bin", but alternates placing dots + binwidth/4 or - binwidth/4 in the off-axis from the bin center. This allows hexagonal packing by setting a stackratio less than 1 (something like 0.9 tends to work). "swarm": uses the "compactswarm" layout from beeswarm::beeswarm(). Does not maintain alignment of rows or columns, but can be more compact and neat looking, especially for sample data (as opposed to quantile dotplots of theoretical distributions, which may look better with "bin", "weave", or "hex"). "bar": for discrete distributions, lays out duplicate values in rectangular bars.
overlaps	<string> How to handle overlapping dots or bins in the "bin", "weave", and "hex" layouts (dots never overlap in the "swarm" or "bar" layouts). For the purposes of this argument, dots are only considered to be overlapping if they would be overlapping when dotsize = 1 and stackratio = 1; i.e. if you set those arguments to other values, overlaps may still occur. One of: "keep": leave overlapping dots as they are. Dots may overlap (usually only slightly) in the "bin", "weave", and "hex" layouts. "nudge": nudge overlapping dots out of the way. Overlaps are avoided using a constrained optimization which minimizes the squared distance of dots to their desired positions, subject to the constraint that adjacent dots do not overlap.
smooth	<function | string> Smoother to apply to dot positions. One of: A function that takes a numeric vector of dot positions and returns a smoothed version of that vector, such as smooth_bounded(), smooth_unbounded(), smooth_discrete()⁠, or ⁠smooth_bar()'. A string indicating what smoother to use, as the suffix to a function name starting with smooth_; e.g. "none" (the default) applies smooth_none(), which simply returns the given vector without applying smoothing. Smoothing is most effective when the smoother is matched to the support of the distribution; e.g. using smooth_bounded(bounds = ...).
overflow	<string> How to handle overflow of dots beyond the extent of the geom when a minimum binwidth (or an exact binwidth) is supplied. One of: "keep": Keep the overflow, drawing dots outside the geom bounds. "warn": Keep the overflow, but produce a warning suggesting solutions, such as setting binwidth = NA or overflow = "compress". "compress": Compress the layout. Reduces the binwidth to the size necessary to keep the dots within bounds, then adjusts stackratio and dotsize so that the apparent dot size is the user-specified minimum binwidth times the user-specified dotsize. If you find the default layout has dots that are too small, and you are okay with dots overlapping, consider setting overflow = "compress" and supplying an exact or minimum dot size using binwidth.
verbose	<scalar logical> If TRUE, print out the bin width of the dotplot. Can be useful if you want to start from an automatically-selected bin width and then adjust it manually. Bin width is printed both as data units and as normalized parent coordinates or "npc"s (see unit()). Note that if you just want to scale the selected bin width to fit within a desired area, it is probably easier to use scale than to copy and scale binwidth manually, and if you just want to provide constraints on the bin width, you can pass a length-2 vector to binwidth.
orientation	<string> Whether this geom is drawn horizontally or vertically. One of: NA (default): automatically detect the orientation based on how the aesthetics are assigned. Automatic detection works most of the time. "horizontal" (or "y"): draw horizontally, using the y aesthetic to identify different groups. For each group, uses the x, xmin, xmax, and thickness aesthetics to draw points, intervals, and slabs. "vertical" (or "x"): draw vertically, using the x aesthetic to identify different groups. For each group, uses the y, ymin, ymax, and thickness aesthetics to draw points, intervals, and slabs. For compatibility with the base ggplot naming scheme for orientation, "x" can be used as an alias for "vertical" and "y" as an alias for "horizontal" (ggdist had an orientation parameter before base ggplot did, hence the discrepancy).
interval_size_domain	<length-2 numeric> Minimum and maximum of the values of the size and linewidth aesthetics that will be translated into actual sizes for intervals drawn according to interval_size_range (see the documentation for that argument.)
interval_size_range	<length-2 numeric> This geom scales the raw size aesthetic values when drawing interval and point sizes, as they tend to be too thick when using the default settings of scale_size_continuous(), which give sizes with a range of c(1, 6). The interval_size_domain value indicates the input domain of raw size values (typically this should be equal to the value of the range argument of the scale_size_continuous() function), and interval_size_range indicates the desired output range of the size values (the min and max of the actual sizes used to draw intervals). Most of the time it is not recommended to change the value of this argument, as it may result in strange scaling of legends; this argument is a holdover from earlier versions that did not have size aesthetics targeting the point and interval separately. If you want to adjust the size of the interval or points separately, you can also use the linewidth or point_size aesthetics; see sub-geometry-scales.
fatten_point	<scalar numeric> A multiplicative factor used to adjust the size of the point relative to the size of the thickest interval line. If you wish to specify point sizes directly, you can also use the point_size aesthetic and scale_point_size_continuous() or scale_point_size_discrete(); sizes specified with that aesthetic will not be adjusted using fatten_point.
arrow	<arrow | NULL> Type of arrow heads to use on the interval, or NULL for no arrows.
show_slab	<scalar logical> Should the slab portion of the geom be drawn?
show_point	<scalar logical> Should the point portion of the geom be drawn?
show_interval	<scalar logical> Should the interval portion of the geom be drawn?
subguide	<function | string> Sub-guide used to annotate the thickness scale. One of: A function that takes a scale argument giving a ggplot2::Scale object and an orientation argument giving the orientation of the geometry and then returns a grid::grob that will draw the axis annotation, such as subguide_axis() (to draw a traditional axis) or subguide_none() (to draw no annotation). See subguide_axis() for a list of possibilities and examples. A string giving the name of such a function when prefixed with "subguide_"; e.g. "axis" or "none". The values "slab", "dots", and "spike" use the default subguide for their geom families (no subguide), which can be modified by setting subguide_slab, subguide_dots, or subguide_spike; see the documentation for those functions.
na.rm	<scalar logical> If FALSE, the default, missing values are removed with a warning. If TRUE, missing values are silently removed.
show.legend	logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes. It can also be a named logical vector to finely select the aesthetics to display.
inherit.aes	If FALSE, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. borders().
check.aes, check.param	If TRUE, the default, will check that supplied parameters and aesthetics are understood by the geom or stat. Use FALSE to suppress the checks.

Details

The dots family of stats and geoms are similar to ggplot2::geom_dotplot() but with a number of differences:

• Dots geoms act like slabs in geom_slabinterval() and can be given x positions (or y positions when in a horizontal orientation).

• Given the available space to lay out dots, the dots geoms will automatically determine how many bins to use to fit the available space.

• Dots geoms use a dynamic layout algorithm that lays out dots from the center out if the input data are symmetrical, guaranteeing that symmetrical data results in a symmetrical plot. The layout algorithm also prevents dots from overlapping each other.

• The shape of the dots in these geoms can be changed using the slab_shape aesthetic (when using the dotsinterval family) or the shape or slab_shape aesthetic (when using the dots family)

Stats and geoms in this family include:

• geom_dots(): dotplots on raw data. Ensures the dotplot fits within available space by reducing the size of the dots automatically (may result in very small dots).

• geom_swarm() and geom_weave(): dotplots on raw data with defaults intended to create "beeswarm" plots. Used side = "both" by default, and sets the default dot size to the same size as geom_point() (binwidth = unit(1.5, "mm")), allowing dots to overlap instead of getting very small.

• stat_dots(): dotplots on raw data, distributional objects, and posterior::rvar()s

• geom_dotsinterval(): dotplot + interval plots on raw data with already-calculated intervals (rarely useful directly).

• stat_dotsinterval(): dotplot + interval plots on raw data, distributional objects, and posterior::rvar()s (will calculate intervals for you).

• geom_blur_dots(): blurry dotplots that allow the standard deviation of a blur applied to each dot to be specified using the sd aesthetic.

• stat_mcse_dots(): blurry dotplots of quantiles using the Monte Carlo Standard Error of each quantile.

stat_dots() and stat_dotsinterval(), when used with the quantiles argument, are particularly useful for constructing quantile dotplots, which can be an effective way to communicate uncertainty using a frequency framing that may be easier for laypeople to understand (Kay et al. 2016, Fernandes et al. 2018).

To visualize sample data, such as a data distribution, samples from a bootstrap distribution, or a Bayesian posterior, you can supply samples to the x or y aesthetic.

To visualize analytical distributions, you can use the xdist or ydist aesthetic. For historical reasons, you can also use dist to specify the distribution, though this is not recommended as it does not work as well with orientation detection. These aesthetics can be used as follows:

• xdist, ydist, and dist can be any distribution object from the distributional package (dist_normal(), dist_beta(), etc) or can be a posterior::rvar() object. Since these functions are vectorized, other columns can be passed directly to them in an aes() specification; e.g. aes(dist = dist_normal(mu, sigma)) will work if mu and sigma are columns in the input data frame.

• dist can be a character vector giving the distribution name. Then the arg1, ... arg9 aesthetics (or args as a list column) specify distribution arguments. Distribution names should correspond to R functions that have "p", "q", and "d" functions; e.g. "norm" is a valid distribution name because R defines the pnorm(), qnorm(), and dnorm() functions for Normal distributions.

  See the parse_dist() function for a useful way to generate dist and args values from human-readable distribution specs (like "normal(0,1)"). Such specs are also produced by other packages (like the brms::get_prior function in brms); thus, parse_dist() combined with the stats described here can help you visualize the output of those functions.

Value

A ggplot2::Geom or ggplot2::Stat representing a dotplot or combined dotplot+interval geometry which can be added to a ggplot() object.

Aesthetics

The dots+interval stats and geoms have a wide variety of aesthetics that control the appearance of their three sub-geometries: the dots (aka the slab), the point, and the interval.

Positional aesthetics

• x: x position of the geometry

• y: y position of the geometry

Dots-specific (aka Slab-specific) aesthetics

• family: The font family used to draw the dots.

• order: The order in which data points are stacked within bins. Can be used to create the effect of "stacked" dots by ordering dots according to a discrete variable. If omitted (NULL), the value of the data points themselves are used to determine stacking order. Only applies when layout is "bin" or "hex", as the other layout methods fully determine both x and y positions.

• side: Which side to place the slab on. "topright", "top", and "right" are synonyms which cause the slab to be drawn on the top or the right depending on if orientation is "horizontal" or "vertical". "bottomleft", "bottom", and "left" are synonyms which cause the slab to be drawn on the bottom or the left depending on if orientation is "horizontal" or "vertical". "topleft" causes the slab to be drawn on the top or the left, and "bottomright" causes the slab to be drawn on the bottom or the right. "both" draws the slab mirrored on both sides (as in a violin plot).

• scale: What proportion of the region allocated to this geom to use to draw the slab. If scale = 1, slabs that use the maximum range will just touch each other. Default is 0.9 to leave some space between adjacent slabs. For a comprehensive discussion and examples of slab scaling and normalization, see the thickness scale article.

• justification: Justification of the interval relative to the slab, where 0 indicates bottom/left justification and 1 indicates top/right justification (depending on orientation). If justification is NULL (the default), then it is set automatically based on the value of side: when side is "top"/"right" justification is set to 0, when side is "bottom"/"left" justification is set to 1, and when side is "both" justification is set to 0.5.

• datatype: When using composite geoms directly without a stat (e.g. geom_slabinterval()), datatype is used to indicate which part of the geom a row in the data targets: rows with datatype = "slab" target the slab portion of the geometry and rows with datatype = "interval" target the interval portion of the geometry. This is set automatically when using ggdist stats.

Interval-specific aesthetics

• xmin: Left end of the interval sub-geometry (if orientation = "horizontal").

• xmax: Right end of the interval sub-geometry (if orientation = "horizontal").

• ymin: Lower end of the interval sub-geometry (if orientation = "vertical").

• ymax: Upper end of the interval sub-geometry (if orientation = "vertical").

Point-specific aesthetics

• shape: Shape type used to draw the point sub-geometry.

Color aesthetics

• colour: (or color) The color of the interval and point sub-geometries. Use the slab_color, interval_color, or point_color aesthetics (below) to set sub-geometry colors separately.

• fill: The fill color of the slab and point sub-geometries. Use the slab_fill or point_fill aesthetics (below) to set sub-geometry colors separately.

• alpha: The opacity of the slab, interval, and point sub-geometries. Use the slab_alpha, interval_alpha, or point_alpha aesthetics (below) to set sub-geometry colors separately.

• colour_ramp: (or color_ramp) A secondary scale that modifies the color scale to "ramp" to another color. See scale_colour_ramp() for examples.

• fill_ramp: A secondary scale that modifies the fill scale to "ramp" to another color. See scale_fill_ramp() for examples.

Line aesthetics

• linewidth: Width of the line used to draw the interval (except with geom_slab(): then it is the width of the slab). With composite geometries including an interval and slab, use slab_linewidth to set the line width of the slab (see below). For interval, raw linewidth values are transformed according to the interval_size_domain and interval_size_range parameters of the geom (see above).

• size: Determines the size of the point. If linewidth is not provided, size will also determines the width of the line used to draw the interval (this allows line width and point size to be modified together by setting only size and not linewidth). Raw size values are transformed according to the interval_size_domain, interval_size_range, and fatten_point parameters of the geom (see above). Use the point_size aesthetic (below) to set sub-geometry size directly without applying the effects of interval_size_domain, interval_size_range, and fatten_point.

• stroke: Width of the outline around the point sub-geometry.

• linetype: Type of line (e.g., "solid", "dashed", etc) used to draw the interval and the outline of the slab (if it is visible). Use the slab_linetype or interval_linetype aesthetics (below) to set sub-geometry line types separately.

Slab-specific color and line override aesthetics

• slab_fill: Override for fill: the fill color of the slab.

• slab_colour: (or slab_color) Override for colour/color: the outline color of the slab.

• slab_alpha: Override for alpha: the opacity of the slab.

• slab_linewidth: Override for linwidth: the width of the outline of the slab.

• slab_linetype: Override for linetype: the line type of the outline of the slab.

• slab_shape: Override for shape: the shape of the dots used to draw the dotplot slab.

Interval-specific color and line override aesthetics

• interval_colour: (or interval_color) Override for colour/color: the color of the interval.

• interval_alpha: Override for alpha: the opacity of the interval.

• interval_linetype: Override for linetype: the line type of the interval.

Point-specific color and line override aesthetics

• point_fill: Override for fill: the fill color of the point.

• point_colour: (or point_color) Override for colour/color: the outline color of the point.

• point_alpha: Override for alpha: the opacity of the point.

• point_size: Override for size: the size of the point.

Deprecated aesthetics

• slab_size: Use slab_linewidth.

• interval_size: Use interval_linewidth.

Other aesthetics (these work as in standard geoms)

• width

• height

• group

See examples of some of these aesthetics in action in vignette("dotsinterval"). Learn more about the sub-geom override aesthetics (like interval_color) in the scales documentation. Learn more about basic ggplot aesthetics in vignette("ggplot2-specs").

Author(s)

Matthew Kay

References

Kay, M., Kola, T., Hullman, J. R., & Munson, S. A. (2016). When (ish) is My Bus? User-centered Visualizations of Uncertainty in Everyday, Mobile Predictive Systems. Conference on Human Factors in Computing Systems - CHI '16, 5092–5103. doi:10.1145/2858036.2858558.

Fernandes, M., Walls, L., Munson, S., Hullman, J., & Kay, M. (2018). Uncertainty Displays Using Quantile Dotplots or CDFs Improve Transit Decision-Making. Conference on Human Factors in Computing Systems - CHI '18. doi:10.1145/3173574.3173718.

See Also

See the stat_slabinterval() family for other stats built on top of geom_slabinterval(). See vignette("dotsinterval") for a variety of examples of use.

Other dotsinterval geoms: geom_blur_dots(), geom_dots(), geom_swarm(), geom_weave()

Examples

library(dplyr)
library(ggplot2)

theme_set(theme_ggdist())

set.seed(12345)
df = tibble(
  g = rep(c("a", "b"), 200),
  value = rnorm(400, c(0, 3), c(0.75, 1))
)


# orientation is detected automatically based on
# which axis is discrete

df %>%
  ggplot(aes(x = value, y = g)) +
  geom_dotsinterval()

df %>%
  ggplot(aes(y = value, x = g)) +
  geom_dotsinterval()


# stat_dots can summarize quantiles, creating quantile dotplots

data(RankCorr_u_tau, package = "ggdist")

RankCorr_u_tau %>%
  ggplot(aes(x = u_tau, y = factor(i))) +
  stat_dots(quantiles = 100)

# color and fill aesthetics can be mapped within the geom
# dotsinterval adds an interval

RankCorr_u_tau %>%
  ggplot(aes(x = u_tau, y = factor(i), fill = after_stat(x > 6))) +
  stat_dotsinterval(quantiles = 100)

---

Multiple-interval plot (shortcut geom)

Description

Shortcut version of geom_slabinterval() for creating multiple-interval plots.

Roughly equivalent to:

geom_slabinterval(
  aes(
    datatype = "interval",
    side = "both"
  ),
  interval_size_range = c(1, 6),
  show_slab = FALSE,
  show_point = FALSE
)

Usage

geom_interval(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  orientation = NA,
  interval_size_range = c(1, 6),
  interval_size_domain = c(1, 6),
  arrow = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  check.aes = TRUE,
  check.param = TRUE
)

Arguments

mapping	Set of aesthetic mappings created by aes(). If specified and inherit.aes = TRUE (the default), it is combined with the default mapping at the top level of the plot. You must supply mapping if there is no plot mapping.
data	The data to be displayed in this layer. There are three options: If NULL, the default, the data is inherited from the plot data as specified in the call to ggplot(). A data.frame, or other object, will override the plot data. All objects will be fortified to produce a data frame. See fortify() for which variables will be created. A function will be called with a single argument, the plot data. The return value must be a data.frame, and will be used as the layer data. A function can be created from a formula (e.g. ~ head(.x, 10)).
stat	The statistical transformation to use on the data for this layer. When using a ⁠geom_*()⁠ function to construct a layer, the stat argument can be used the override the default coupling between geoms and stats. The stat argument accepts the following: A Stat ggproto subclass, for example StatCount. A string naming the stat. To give the stat as a string, strip the function name of the stat_ prefix. For example, to use stat_count(), give the stat as "count". For more information and other ways to specify the stat, see the layer stat documentation.
position	<Position | string> Position adjustment, either as a string, or the result of a call to a position adjustment function. Setting this equal to "dodge" (position_dodge()) or "dodgejust" (position_dodgejust()) can be useful if you have overlapping geometries.
...	Other arguments passed to layer(). These are often aesthetics, used to set an aesthetic to a fixed value, like colour = "red" or linewidth = 3 (see Aesthetics, below). They may also be parameters to the paired geom/stat.
orientation	<string> Whether this geom is drawn horizontally or vertically. One of: NA (default): automatically detect the orientation based on how the aesthetics are assigned. Automatic detection works most of the time. "horizontal" (or "y"): draw horizontally, using the y aesthetic to identify different groups. For each group, uses the x, xmin, xmax, and thickness aesthetics to draw points, intervals, and slabs. "vertical" (or "x"): draw vertically, using the x aesthetic to identify different groups. For each group, uses the y, ymin, ymax, and thickness aesthetics to draw points, intervals, and slabs. For compatibility with the base ggplot naming scheme for orientation, "x" can be used as an alias for "vertical" and "y" as an alias for "horizontal" (ggdist had an orientation parameter before base ggplot did, hence the discrepancy).
interval_size_range	<length-2 numeric> This geom scales the raw size aesthetic values when drawing interval and point sizes, as they tend to be too thick when using the default settings of scale_size_continuous(), which give sizes with a range of c(1, 6). The interval_size_domain value indicates the input domain of raw size values (typically this should be equal to the value of the range argument of the scale_size_continuous() function), and interval_size_range indicates the desired output range of the size values (the min and max of the actual sizes used to draw intervals). Most of the time it is not recommended to change the value of this argument, as it may result in strange scaling of legends; this argument is a holdover from earlier versions that did not have size aesthetics targeting the point and interval separately. If you want to adjust the size of the interval or points separately, you can also use the linewidth or point_size aesthetics; see sub-geometry-scales.
interval_size_domain	<length-2 numeric> Minimum and maximum of the values of the size and linewidth aesthetics that will be translated into actual sizes for intervals drawn according to interval_size_range (see the documentation for that argument.)
arrow	<arrow | NULL> Type of arrow heads to use on the interval, or NULL for no arrows.
na.rm	<scalar logical> If FALSE, the default, missing values are removed with a warning. If TRUE, missing values are silently removed.
show.legend	logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes. It can also be a named logical vector to finely select the aesthetics to display.
inherit.aes	If FALSE, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. borders().
check.aes, check.param	If TRUE, the default, will check that supplied parameters and aesthetics are understood by the geom or stat. Use FALSE to suppress the checks.

Details

This geom wraps geom_slabinterval() with defaults designed to produce multiple-interval plots. Default aesthetic mappings are applied if the .width column is present in the input data (e.g., as generated by the point_interval() family of functions), making this geom often more convenient than vanilla ggplot2 geometries when used with functions like median_qi(), mean_qi(), mode_hdi(), etc.

Specifically, if .width is present in the input, geom_interval() acts as if its default aesthetics are aes(colour = forcats::fct_rev(ordered(.width)))

Value

A ggplot2::Geom representing a multiple-interval geometry which can be added to a ggplot() object.

Aesthetics

The slab+interval stats and geoms have a wide variety of aesthetics that control the appearance of their three sub-geometries: the slab, the point, and the interval.

Positional aesthetics

• x: x position of the geometry

• y: y position of the geometry

Interval-specific aesthetics

• xmin: Left end of the interval sub-geometry (if orientation = "horizontal").

• xmax: Right end of the interval sub-geometry (if orientation = "horizontal").

• ymin: Lower end of the interval sub-geometry (if orientation = "vertical").

• ymax: Upper end of the interval sub-geometry (if orientation = "vertical").

Color aesthetics

• colour: (or color) The color of the interval and point sub-geometries. Use the slab_color, interval_color, or point_color aesthetics (below) to set sub-geometry colors separately.

• fill: The fill color of the slab and point sub-geometries. Use the slab_fill or point_fill aesthetics (below) to set sub-geometry colors separately.

• alpha: The opacity of the slab, interval, and point sub-geometries. Use the slab_alpha, interval_alpha, or point_alpha aesthetics (below) to set sub-geometry colors separately.

• colour_ramp: (or color_ramp) A secondary scale that modifies the color scale to "ramp" to another color. See scale_colour_ramp() for examples.

• fill_ramp: A secondary scale that modifies the fill scale to "ramp" to another color. See scale_fill_ramp() for examples.

Line aesthetics

• linewidth: Width of the line used to draw the interval (except with geom_slab(): then it is the width of the slab). With composite geometries including an interval and slab, use slab_linewidth to set the line width of the slab (see below). For interval, raw linewidth values are transformed according to the interval_size_domain and interval_size_range parameters of the geom (see above).

• size: Determines the size of the point. If linewidth is not provided, size will also determines the width of the line used to draw the interval (this allows line width and point size to be modified together by setting only size and not linewidth). Raw size values are transformed according to the interval_size_domain, interval_size_range, and fatten_point parameters of the geom (see above). Use the point_size aesthetic (below) to set sub-geometry size directly without applying the effects of interval_size_domain, interval_size_range, and fatten_point.

• stroke: Width of the outline around the point sub-geometry.

• linetype: Type of line (e.g., "solid", "dashed", etc) used to draw the interval and the outline of the slab (if it is visible). Use the slab_linetype or interval_linetype aesthetics (below) to set sub-geometry line types separately.

Interval-specific color and line override aesthetics

• interval_colour: (or interval_color) Override for colour/color: the color of the interval.

• interval_alpha: Override for alpha: the opacity of the interval.

• interval_linetype: Override for linetype: the line type of the interval.

Deprecated aesthetics

• interval_size: Use interval_linewidth.

Other aesthetics (these work as in standard geoms)

• width

• height

• group

See examples of some of these aesthetics in action in vignette("slabinterval"). Learn more about the sub-geom override aesthetics (like interval_color) in the scales documentation. Learn more about basic ggplot aesthetics in vignette("ggplot2-specs").

See Also

See stat_interval() for the stat version, intended for use on sample data or analytical distributions. See geom_slabinterval() for the geometry this shortcut is based on.

Other slabinterval geoms: geom_pointinterval(), geom_slab(), geom_spike()

Examples

library(dplyr)
library(ggplot2)

theme_set(theme_ggdist())

data(RankCorr_u_tau, package = "ggdist")

# orientation is detected automatically based on
# use of xmin/xmax or ymin/ymax

RankCorr_u_tau %>%
  group_by(i) %>%
  median_qi(.width = c(.5, .8, .95, .99)) %>%
  ggplot(aes(y = i, x = u_tau, xmin = .lower, xmax = .upper)) +
  geom_interval() +
  scale_color_brewer()

RankCorr_u_tau %>%
  group_by(i) %>%
  median_qi(.width = c(.5, .8, .95, .99)) %>%
  ggplot(aes(x = i, y = u_tau, ymin = .lower, ymax = .upper)) +
  geom_interval() +
  scale_color_brewer()

---

Line + multiple-ribbon plots (ggplot geom)

Description

A combination of geom_line() and geom_ribbon() with default aesthetics designed for use with output from point_interval().

Usage

geom_lineribbon(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  step = FALSE,
  orientation = NA,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  check.aes = TRUE,
  check.param = TRUE
)

Arguments

mapping	Set of aesthetic mappings created by aes(). If specified and inherit.aes = TRUE (the default), it is combined with the default mapping at the top level of the plot. You must supply mapping if there is no plot mapping.
data	The data to be displayed in this layer. There are three options: If NULL, the default, the data is inherited from the plot data as specified in the call to ggplot(). A data.frame, or other object, will override the plot data. All objects will be fortified to produce a data frame. See fortify() for which variables will be created. A function will be called with a single argument, the plot data. The return value must be a data.frame, and will be used as the layer data. A function can be created from a formula (e.g. ~ head(.x, 10)).
stat	The statistical transformation to use on the data for this layer. When using a ⁠geom_*()⁠ function to construct a layer, the stat argument can be used the override the default coupling between geoms and stats. The stat argument accepts the following: A Stat ggproto subclass, for example StatCount. A string naming the stat. To give the stat as a string, strip the function name of the stat_ prefix. For example, to use stat_count(), give the stat as "count". For more information and other ways to specify the stat, see the layer stat documentation.
position	A position adjustment to use on the data for this layer. This can be used in various ways, including to prevent overplotting and improving the display. The position argument accepts the following: The result of calling a position function, such as position_jitter(). This method allows for passing extra arguments to the position. A string naming the position adjustment. To give the position as a string, strip the function name of the position_ prefix. For example, to use position_jitter(), give the position as "jitter". For more information and other ways to specify the position, see the layer position documentation.
...	Other arguments passed to layer(). These are often aesthetics, used to set an aesthetic to a fixed value, like colour = "red" or linewidth = 3 (see Aesthetics, below). They may also be parameters to the paired geom/stat.
step	<scalar logical | string> Should the line/ribbon be drawn as a step function? One of: FALSE (default): do not draw as a step function. "mid" (or TRUE): draw steps midway between adjacent x values. "hv": draw horizontal-then-vertical steps. "vh": draw as vertical-then-horizontal steps. TRUE is an alias for "mid", because for a step function with ribbons "mid" is reasonable default (for the other two step approaches the ribbons at either the very first or very last x value will not be visible).
orientation	<string> Whether this geom is drawn horizontally or vertically. One of: NA (default): automatically detect the orientation based on how the aesthetics are assigned. Automatic detection works most of the time. "horizontal" (or "y"): draw horizontally, using the y aesthetic to identify different groups. For each group, uses the x, xmin, xmax, and thickness aesthetics to draw points, intervals, and slabs. "vertical" (or "x"): draw vertically, using the x aesthetic to identify different groups. For each group, uses the y, ymin, ymax, and thickness aesthetics to draw points, intervals, and slabs. For compatibility with the base ggplot naming scheme for orientation, "x" can be used as an alias for "vertical" and "y" as an alias for "horizontal" (ggdist had an orientation parameter before base ggplot did, hence the discrepancy).
na.rm	<scalar logical> If FALSE, the default, missing values are removed with a warning. If TRUE, missing values are silently removed.
show.legend	logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes. It can also be a named logical vector to finely select the aesthetics to display.
inherit.aes	If FALSE, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. borders().
check.aes, check.param	If TRUE, the default, will check that supplied parameters and aesthetics are understood by the geom or stat. Use FALSE to suppress the checks.

Details

geom_lineribbon() is a combination of a geom_line() and geom_ribbon() designed for use with output from point_interval(). This geom sets some default aesthetics equal to the .width column generated by the point_interval() family of functions, making them often more convenient than a vanilla geom_ribbon() + geom_line().

Specifically, geom_lineribbon() acts as if its default aesthetics are aes(fill = forcats::fct_rev(ordered(.width))).

Value

A ggplot2::Geom representing a combined line + multiple-ribbon geometry which can be added to a ggplot() object.

Aesthetics

The line+ribbon stats and geoms have a wide variety of aesthetics that control the appearance of their two sub-geometries: the line and the ribbon.

Positional aesthetics

• x: x position of the geometry

• y: y position of the geometry

Ribbon-specific aesthetics

• xmin: Left edge of the ribbon sub-geometry (if orientation = "horizontal").

• xmax: Right edge of the ribbon sub-geometry (if orientation = "horizontal").

• ymin: Lower edge of the ribbon sub-geometry (if orientation = "vertical").

• ymax: Upper edge of the ribbon sub-geometry (if orientation = "vertical").

• order: The order in which ribbons are drawn. Ribbons with the smallest mean value of order are drawn first (i.e., will be drawn below ribbons with larger mean values of order). If order is not supplied to geom_lineribbon(), -abs(xmax - xmin) or -abs(ymax - ymax) (depending on orientation) is used, having the effect of drawing the widest (on average) ribbons on the bottom. stat_lineribbon() uses order = after_stat(level) by default, causing the ribbons generated from the largest .width to be drawn on the bottom.

Color aesthetics

• colour: (or color) The color of the line sub-geometry.

• fill: The fill color of the ribbon sub-geometry.

• alpha: The opacity of the line and ribbon sub-geometries.

• fill_ramp: A secondary scale that modifies the fill scale to "ramp" to another color. See scale_fill_ramp() for examples.

Line aesthetics

• linewidth: Width of line. In ggplot2 < 3.4, was called size.

• linetype: Type of line (e.g., "solid", "dashed", etc)

Other aesthetics (these work as in standard geoms)

• group

See examples of some of these aesthetics in action in vignette("lineribbon"). Learn more about the sub-geom override aesthetics (like interval_color) in the scales documentation. Learn more about basic ggplot aesthetics in vignette("ggplot2-specs").

Author(s)

Matthew Kay

See Also

See stat_lineribbon() for a version that does summarizing of samples into points and intervals within ggplot. See geom_pointinterval() for a similar geom intended for point summaries and intervals. See geom_line() and geom_ribbon() and for the geoms this is based on.

Examples

library(dplyr)
library(ggplot2)

theme_set(theme_ggdist())

set.seed(12345)
tibble(
  x = rep(1:10, 100),
  y = rnorm(1000, x)
) %>%
  group_by(x) %>%
  median_qi(.width = c(.5, .8, .95)) %>%
  ggplot(aes(x = x, y = y, ymin = .lower, ymax = .upper)) +
  # automatically uses aes(fill = forcats::fct_rev(ordered(.width)))
  geom_lineribbon() +
  scale_fill_brewer()

---