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 mjskay@northwestern.edu

Other contributors:

• Brenton M. Wiernik brenton@wiernik.org [contributor]

See Also

Useful links:

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

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

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

Base ggproto classes for ggdist

Description

Base ggproto classes for ggdist

See Also

ggproto()

Probability expressions in ggdist aesthetics

Description

Experimental probability-like expressions that can be used in place of some after_stat() expressions in aesthetic assignments in ggdist stats.

Usage

Pr_(x)

p_(x)

Arguments

Details

Pr_() and p_() are an experimental mini-language for specifying aesthetic values based on probabilities and probability densities derived from distributions supplied to ggdist stats (e.g., in stat_slabinterval(), stat_dotsinterval(), etc.). They generate expressions that use after_stat() and the computed variables of the stat (such as cdf and pdf; see e.g. the Computed Variables section of stat_slabinterval()) to compute the desired probabilities or densities.

For example, one way to map the density of a distribution onto the alpha aesthetic of a slab is to use after_stat(pdf):

ggplot() +
  stat_slab(aes(xdist = distributional::dist_normal(), alpha = after_stat(pdf)))

ggdist probability expressions offer an alternative, equivalent syntax:

ggplot() +
  stat_slab(aes(xdist = distributional::dist_normal(), alpha = !!p_(x)))

Where p_(x) is the probability density function. The use of ⁠!!⁠ is necessary to splice the generated expression into the aes() call; for more information, see quasiquotation.

Probability expressions

Probability expressions consist of a call to Pr_() or p_() containing a small number of valid combinations of operators and variable names.

Valid variables in probability expressions include:

• x, y, or value: values along the x or y axis. value is the orientation-neutral form.

• xdist, ydist, or dist: distributions mapped along the x or y axis. dist is the orientation-neutral form. X and Y can also be used as synonyms for xdist and ydist.

• interval: the smallest interval containing the current x/y value.

Pr_() generates expressions for probabilities, e.g. cumulative distribution functions (CDFs). Valid operators inside Pr_() are:

• <, <=, >, >=: generates values of the cumulative distribution function (CDF) or complementary CDF by comparing one of {x, y, value} to one of {xdist, ydist, dist, X, Y}. For example, Pr_(xdist <= x) gives the CDF and Pr_(xdist > x) gives the CCDF.

• %in%: currently can only be used with interval on the right-hand side: gives the probability of {x, y, value} (left-hand side) being in the smallest interval the stat generated that contains the value; e.g. Pr_(x %in% interval).

p_() generates expressions for probability density functions or probability mass functions (depending on if the underlying distribution is continuous or discrete). It currently does not allow any operators in the expression, and must be passed one of x, y, or value.

See Also

The Computed Variables section of stat_slabinterval() (especially cdf and pdf) and the after_stat() function.

Examples

library(ggplot2)
library(distributional)

df = data.frame(
  d = c(dist_normal(2.7, 1), dist_lognormal(1, 1/3)),
  name = c("normal", "lognormal")
)

# map density onto alpha of the fill
ggplot(df, aes(y = name, xdist = d)) +
  stat_slabinterval(aes(alpha = !!p_(x)))

# map CCDF onto thickness (like stat_ccdfinterval())
ggplot(df, aes(y = name, xdist = d)) +
  stat_slabinterval(aes(thickness = !!Pr_(xdist > x)))

# map containing interval onto fill
ggplot(df, aes(y = name, xdist = d)) +
  stat_slabinterval(aes(fill = !!Pr_(x %in% interval)))

# the color scale in the previous example is not great, so turn the
# probability into an ordered factor and adjust the fill scale.
# Though, see also the `level` computed variable in `stat_slabinterval()`,
# which is probably easier to use to create this style of chart.
ggplot(df, aes(y = name, xdist = d)) +
  stat_slabinterval(aes(fill = ordered(!!Pr_(x %in% interval)))) +
  scale_fill_brewer(direction = -1)

Thinned subset of posterior sample from a Bayesian analysis of perception of correlation.

Description

Data from Kay and Heer (2016), primarily used for testing and examples.

Details

For more details, see Kay and Heer (2016) or the Github repository describing the analysis: https://github.com/mjskay/ranking-correlation. The original experiment (but not this analysis of it) is described in Harrison et al. (2014).

data("RankCorr") is a substantially thinned version of the original posterior sample and has omitted several parameters in order for it to be a more manageable size.

data("RankCorr_u_tau") is used for testing and examples and is roughly the equivalent of the following:

data("RankCorr")
RankCorr_u_tau = tidybayes::spread_draws(RankCorr, u_tau[i]))

References

Kay, Matthew, and Jeffrey Heer. (2016). "Beyond Weber's law: A second look at ranking visualizations of correlation." IEEE transactions on visualization and computer graphics 22(1): 469-478. doi:10.1109/TVCG.2015.2467671

Harrison, Lane, Fumeng Yang, Steven Franconeri, and Remco Chang. (2014). "Ranking visualizations of correlation using Weber's law." IEEE transactions on visualization and computer graphics 20(12): 1943-1952. doi:10.1109/TVCG.2014.2346979

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

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

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

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

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

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

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

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 ith order statistic of x (i.e. its ith-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

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

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

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

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

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

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

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

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

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

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

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

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

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()

Point + multiple-interval plot (shortcut geom)

Description

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

Roughly equivalent to:

geom_slabinterval(
  aes(
    datatype = "interval",
    side = "both"
  ),
  show_slab = FALSE,
  show.legend = c(size = FALSE)
)

Usage

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

Arguments

Details

This geom wraps geom_slabinterval() with defaults designed to produce point + 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_pointinterval() acts as if its default aesthetics are aes(size = -.width)

Value

A ggplot2::Geom representing a point + 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").

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.

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

• 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_pointinterval() 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_interval(), geom_slab(), geom_spike()

Examples

library(dplyr)
library(ggplot2)

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(.8, .95)) %>%
  ggplot(aes(y = i, x = u_tau, xmin = .lower, xmax = .upper)) +
  geom_pointinterval()

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

Slab (ridge) plot (shortcut geom)

Description

Shortcut version of geom_slabinterval() for creating slab (ridge) plots.

Roughly equivalent to:

geom_slabinterval(
  show_point = FALSE,
  show_interval = FALSE
)

Usage

geom_slab(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  orientation = NA,
  subscale = "thickness",
  normalize = "all",
  fill_type = "segments",
  subguide = "slab",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  check.aes = TRUE,
  check.param = TRUE
)

Arguments

Value

A ggplot2::Geom representing a slab (ridge) 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

Slab-specific aesthetics

• thickness: The thickness of the slab at each x value (if orientation = "horizontal") or y value (if orientation = "vertical") of the slab.

• 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.

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.

Deprecated aesthetics

• slab_size: Use slab_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_slab() 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_interval(), geom_pointinterval(), geom_spike()

Examples

library(dplyr)
library(ggplot2)

theme_set(theme_ggdist())

# we will manually demonstrate plotting a density with geom_slab(),
# though generally speaking this is easier to do using stat_slab(), which
# will determine sensible limits automatically and correctly adjust
# densities when using scale transformations
df = expand.grid(
    mean = 1:3,
    input = seq(-2, 6, length.out = 100)
  ) %>%
  mutate(
    group = letters[4 - mean],
    density = dnorm(input, mean, 1)
  )

# orientation is detected automatically based on
# use of x or y
df %>%
  ggplot(aes(y = group, x = input, thickness = density)) +
  geom_slab()

df %>%
  ggplot(aes(x = group, y = input, thickness = density)) +
  geom_slab()

# RIDGE PLOTS
# "ridge" plots can be created by increasing the slab height and
# setting the slab color
df %>%
  ggplot(aes(y = group, x = input, thickness = density)) +
  geom_slab(height = 2, color = "black")

Slab + point + interval meta-geom

Description

This meta-geom supports drawing combinations of functions (as slabs, aka ridge plots or joy plots), points, and intervals. It acts as a meta-geom for many other ggdist geoms that are wrappers around this geom, including eye plots, half-eye plots, CCDF barplots, and point+multiple interval plots, and supports both horizontal and vertical orientations, dodging (via the position argument), and relative justification of slabs with their corresponding intervals.

Usage

geom_slabinterval(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  orientation = NA,
  subscale = "thickness",
  normalize = "all",
  fill_type = "segments",
  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

Details

geom_slabinterval() is a flexible meta-geom that you can use directly or through a variety of "shortcut" geoms that represent useful combinations of the various parameters of this geom. In many cases you will want to use the shortcut geoms instead as they create more useful mnemonic primitives, such as eye plots, half-eye plots, point+interval plots, or CCDF barplots.

The slab portion of the geom is much like a ridge or "joy" plot: it represents the value of a function scaled to fit between values on the x or y axis (depending on the value of orientation). Values of the functions are specified using the thickness aesthetic and are scaled to fit into scale times the distance between points on the relevant axis. E.g., if orientation is "horizontal", scale is 0.9, and y is a discrete variable, then the thickness aesthetic specifies the value of some function of x that is drawn for every y value and scaled to fit into 0.9 times the distance between points on the y axis.

For the interval portion of the geom, x and y aesthetics specify the location of the point, and ymin/ymax or xmin/xmax (depending on the value of orientation) specify the endpoints of the interval. A scaling factor for interval line width and point size is applied through the interval_size_domain, interval_size_range, and fatten_point parameters. These scaling factors are designed to give multiple uncertainty intervals reasonable scaling at the default settings for scale_size_continuous().

As a combination geom, this geom expects a datatype aesthetic specifying which part of the geom a given row in the input data corresponds to: "slab" or "interval". However, specifying this aesthetic manually is typically only necessary if you use this geom directly; the numerous wrapper geoms will usually set this aesthetic for you as needed, and their use is recommended unless you have a very custom use case.

Wrapper geoms include:

• geom_pointinterval()

• geom_interval()

• geom_slab()

In addition, the stat_slabinterval() family of stats uses geoms from the geom_slabinterval() family, and is often easier to use than using these geoms directly. Typically, the ⁠geom_*⁠ versions are meant for use with already-summarized data (such as intervals) and the ⁠stat_*⁠ versions are summarize the data themselves (usually draws from a distribution) to produce the geom.

Value

A ggplot2::Geom representing a slab or combined slab+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

Slab-specific aesthetics

• thickness: The thickness of the slab at each x value (if orientation = "horizontal") or y value (if orientation = "vertical") of the slab.

• 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.

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("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").

Author(s)

Matthew Kay

See Also

See geom_lineribbon() for a combination geom designed for fit curves plus probability bands. See geom_dotsinterval() for a combination geom designed for plotting dotplots with intervals. See stat_slabinterval() for families of stats built on top of this geom for common use cases (like stat_halfeye()). See vignette("slabinterval") for a variety of examples of use.

Examples

# geom_slabinterval() is typically not that useful on its own.
# See vignette("slabinterval") for a variety of examples of the use of its
# shortcut geoms and stats, which are more useful than using
# geom_slabinterval() directly.

Spike plot (ggplot2 geom)

Description

Geometry for drawing "spikes" (optionally with points on them) on top of geom_slabinterval() geometries: this geometry understands the scaling and positioning of the thickness aesthetic from geom_slabinterval(), which allows you to position spikes and points along a slab.

Usage

geom_spike(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  subguide = "spike",
  orientation = NA,
  subscale = "thickness",
  normalize = "all",
  arrow = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  check.aes = TRUE,
  check.param = TRUE
)

Arguments

Details

This geometry consists of a "spike" (vertical/horizontal line segment) and a "point" (at the end of the line segment). It uses the thickness aesthetic to determine where the endpoint of the line is, which allows it to be used with geom_slabinterval() geometries for labeling specific values of the thickness function.

Value

A ggplot2::Geom representing a spike geometry which can be added to a ggplot() object. rd_slabinterval_aesthetics(geom_name),

Aesthetics

The spike geom has a wide variety of aesthetics that control the appearance of its two sub-geometries: the spike and the point.

Positional aesthetics

• x: x position of the geometry

• y: y position of the geometry

Spike-specific (aka Slab-specific) aesthetics

• thickness: The thickness of the slab at each x value (if orientation = "horizontal") or y value (if orientation = "vertical") of the slab.

• 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.

Color aesthetics

• colour: (or color) The color of the spike and point sub-geometries.

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

• alpha: The opacity of the spike and point sub-geometries.

• 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 spike sub-geometry.

• size: Size of the point sub-geometry.

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

• linetype: Type of line (e.g., "solid", "dashed", etc) used to draw the spike.

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_spike() for the stat version, intended for use on sample data or analytical distributions.

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

Examples

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

# geom_spike is easiest to use with distributional or
# posterior::rvar objects
df = tibble(
  d = dist_normal(1:2, 1:2), g = c("a", "b")
)

# annotate the density at the mean of a distribution
df %>% mutate(
  mean = mean(d),
  density(d, list(density_at_mean = mean))
) %>%
  ggplot(aes(y = g)) +
  stat_slab(aes(xdist = d)) +
  geom_spike(aes(x = mean, thickness = density_at_mean)) +
  # need shared thickness scale so that stat_slab and geom_spike line up
  scale_thickness_shared()

# annotate the endpoints of intervals of a distribution
# here we'll use an arrow instead of a point by setting size = 0
arrow_spec = arrow(angle = 45, type = "closed", length = unit(4, "pt"))
df %>% mutate(
  median_qi(d, .width = 0.9),
  density(d, list(density_lower = .lower, density_upper = .upper))
) %>%
  ggplot(aes(y = g)) +
  stat_halfeye(aes(xdist = d), .width = 0.9, color = "gray35") +
  geom_spike(
    aes(x = .lower, thickness = density_lower),
    size = 0, arrow = arrow_spec, color = "blue", linewidth = 0.75
  ) +
  geom_spike(
    aes(x = .upper, thickness = density_upper),
    size = 0, arrow = arrow_spec, color = "red", linewidth = 0.75
  ) +
  scale_thickness_shared()

Beeswarm plot (shortcut geom)

Description

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

Roughly equivalent to:

geom_dots(
  aes(side = "both"),
  overflow = "compress",
  binwidth = unit(1.5, "mm"),
  layout = "swarm"
)

Usage

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

Arguments

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 beeswarm 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.