Movatterモバイル変換

Visualizations of Distributions and Uncertainty

Description

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

Details

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

Thegeom_slabinterval() /stat_slabinterval() family (seevignette("slabinterval")) makes iteasy to visualize point summaries and intervals, eye plots, half-eye plots, ridge plots,CCDF bar plots, gradient plots, histograms, and more.

Thegeom_dotsinterval() /stat_dotsinterval() family (seevignette("dotsinterval")) makesit easy to visualize dot+interval plots, Wilkinson dotplots, beeswarm plots, and quantile dotplots.

Thegeom_lineribbon() /stat_lineribbon() family (seevignette("lineribbon"))makes it easy to visualize fit lines with an arbitrary number of uncertainty bands.

Author(s)

Maintainer: Matthew Kaymjskay@northwestern.edu

Other contributors:

• Brenton M. Wiernikbrenton@wiernik.org [contributor]

See Also

Useful links:

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

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

• Report bugs athttps://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 ofsomeafter_stat() expressions in aesthetic assignments inggdist stats.

Usage

Pr_(x)p_(x)

Arguments

Details

Pr_() andp_() are anexperimental mini-language for specifying aesthetic valuesbased on probabilities and probability densities derived from distributionssupplied toggdist stats (e.g., instat_slabinterval(),stat_dotsinterval(), etc.). They generate expressions that useafter_stat()and the computed variables of the stat (such ascdf andpdf; see e.g.theComputed Variables section ofstat_slabinterval()) to computethe desired probabilities or densities.

For example, one way to map the density of a distribution onto thealphaaesthetic of a slab is to useafter_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)))

Wherep_(x) is the probability density function. The use of⁠!!⁠ isnecessary to splice the generated expression into theaes() call; formore information, seequasiquotation.

Probability expressions

Probability expressions consist of a call toPr_() orp_() containinga small number of valid combinations of operators and variable names.

Valid variables in probability expressions include:

• x,y, orvalue: values along thex ory axis.value is theorientation-neutral form.

• xdist,ydist, ordist: distributions mapped along thex oryaxis.dist is the orientation-neutral form.X andY can also beused as synonyms forxdist andydist.

• interval: the smallest interval containing the currentx/y value.

Pr_() generates expressions for probabilities, e.g. cumulative distributionfunctions (CDFs). Valid operators insidePr_() are:

• <,<=,>,>=: generates values of the cumulative distributionfunction (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 andPr_(xdist > x) gives the CCDF.

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

p_() generates expressions for probability density functions or probability massfunctions (depending on if the underlying distribution is continuous ordiscrete). It currently does not allow any operators in the expression, andmust be passed one ofx,y, orvalue.

See Also

TheComputed Variables section ofstat_slabinterval() (especiallycdf andpdf) and theafter_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 fillggplot(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 fillggplot(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 Harrisonet al. (2014).

data("RankCorr") is a substantially thinned version of the original posterior sample and has omitted severalparameters 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 thealignargument todensity_histogram().

Supportsautomatic partial function application withwaived 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-spacedbreaks givingbin edges and return a numeric offset which, if subtracted frombreaks,will align them as desired:

• align_none() performs no alignment (it always returns0).

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

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

Foralign_boundary() (respectivelyalign_center()), if no bin edge (or center) in therange ofbreaks would line up withat, it ensures thatat is an integermultiple of the bin width away from a bin edge (or center).

Value

A scalar numeric returning an offset to be subtracted frombreaks.

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

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

Functions supporting automatic partial application include:

• Thepoint_interval() family, such asmedian_qi(),mean_qi(),mode_hdi(), etc.

• Thesmooth_ family, such assmooth_bounded(),smooth_unbounded(),smooth_discrete(), andsmooth_bar().

• Thedensity_ family, such asdensity_bounded(),density_unbounded() anddensity_histogram().

• Thealign family.

• Thebreaks family.

• Thebandwidth family.

• Theblur family.

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

• 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 forggdist functions work similarly; e.g.density,align,breaks,bandwidth, andpoint_interval arguments.

These function families (exceptpoint_interval()) also support passingwaivers to their optional arguments: ifwaiver() is passed to anyof these arguments, their default value (or the mostrecently-partially-applied non-waiver value) is used instead.

Use theauto_partial() function to create new functions that supportautomatic partial application.

Usage

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

Arguments

Value

A modified version off that will automatically be partiallyapplied 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-isdensity_unbounded()# we could create a new function that uses half the default bandwidthdensity_half_bw = density_unbounded(adjust = 0.5)density_half_bw# we can overwrite partially-applied argumentsdensity_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 fardensity_quarter_bw_trimmed(x)# create a custom automatically partially applied functionf = auto_partial(function(x, y, z = 3) (x + y) * z)f()f(1)g = f(y = 2)(z = 4)gg(1)# pass waiver() to optional arguments to use existing valuesf(z = waiver())(1, 2)  # uses default z = 3f(z = 4)(z = waiver())(1, 2)  # uses z = 4

Bandwidth estimators

Description

Bandwidth estimators for densities, used in thebandwidth argumentto density functions (e.g.density_bounded(),density_unbounded()).

Supportsautomatic partial function application withwaived 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 correspondingbw.-prefixed functionsinstats. See, for example,bw.SJ().

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

With the exception ofbandwidth_nrd0(), these estimators may fail in somecases, often when a sample contains many duplicates. If they do they willautomatically fall back tobandwidth_nrd0() with a warning. However, thesefailures are typically symptomatic of situations where you should not want touse a kernel density estimator in the first place (e.g. data with duplicatesand/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

Adata.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 whenlayout = "swarm")

See Also

find_dotplot_binwidth() for an algorithm that finds good bin widthsto use with this function;geom_dotsinterval() for geometries that usethese 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 theblur argument togeom_blur_dots() orstat_mcse_dots().

Supportsautomatic partial function application withwaived arguments.

Usage

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

Arguments

Details

These functions are passedx,r, andsd whengeom_blur_dots()draws in order to create a radial gradient representing each dot in thedotplot. They return values between0 and1 giving the opacity of thedot at each value ofx.

blur_gaussian() creates a dot with radiusr that has a Gaussian blur withstandard deviationsd applied to it. It does this by calculating\alpha(x; r, \sigma), the opacity at distancex from the centerof a dot with radiusr that has had a Gaussian blur with standarddeviation\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 thedot at 50% opacity, where the interval is a Gaussian quantile interval withmass equal to.width and standard deviationsd.

Value

A vector with the same length asx giving the opacity of the radialgradient representing the dot at eachx value.

See Also

geom_blur_dots() andstat_mcse_dots() for geometries making use ofblur 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 ofthe order statistics of the sample. Use with thebounder argument todensity_bounded().

Supportsautomatic partial function application withwaived arguments.

Usage

bounder_cdf(x, p = 0.01)

Arguments

Details

bounder_cdf() uses the distribution of the order statistics ofX to estimate where the first and last order statistics (i.e. themin and max) of this distribution would be, assuming the samplex is thedistribution. Then, it adjusts the boundary outwards frommin(x) (ormax(x))by the distance betweenmin(x) (ormax(x)) and the nearest estimatedorder statistic.

TakingX =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 eachorder statistic in terms of the quantile function ofX (which wecan estimate from the data), giving us an estimate for the minimumand 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 onp, the percentile of the distribution of the orderstatistic used to form the estimate. Whilep = 0.5 (the median) might bea reasonable choice (and gives results similar tobounder_cooke()), this tendsto be a bit too aggressive in "detecting" bounded distributions, especially insmall sample sizes. Thus, we use a default ofp = 0.01, which tends tobe very conservative in small samples (in that it usually gives resultsroughly equivalent to an unbounded distribution), but which still performswell 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 boundsof the distribution thatx came from.

See Also

Thebounder argument todensity_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 thebounder argument todensity_bounded().

Supportsautomatic partial function application withwaived 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]

WhereX_{(i)} is theith order statistic ofx (i.e. itsith-smallest value).

Value

A length-2 numeric vector giving an estimate of the minimum and maximum boundsof the distribution thatx 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 resamplingmethods.The Annals of Statistics 12(4), 1543–1550.doi:10.1214/aos/1176346811

See Also

Thebounder argument todensity_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 thebounder argument todensity_bounded().

Supportsautomatic partial function application withwaived arguments.

Usage

bounder_range(x)

Arguments

Details

Estimate the bounds of a distribution usingrange(x).

Value

A length-2 numeric vector giving an estimate of the minimum and maximum boundsof the distribution thatx came from.

See Also

Thebounder argument todensity_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 thebreaksargument todensity_histogram().

Supportsautomatic partial function application withwaived 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 forthebreaks argument todensity_histogram() that will determine the histogrambreaks.

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

• breaks_Sturges(),breaks_Scott(), andbreaks_FD() implement weightedversions of their corresponding base functions. They return a scalarnumeric giving the number of bins. Seenclass.Sturges(),nclass.scott(),andnclass.FD().

• breaks_quantiles() constructs irregularly-sized bins usingmax_n + 1(possibly weighted) quantiles ofx. The final number of bins isat mostmax_n, as small bins (ones whose bin width is less than halfthe range of the data divided bymax_n timesmin_width) will be mergedinto adjacent bins.

Value

Either a single number (giving the number of bins) or a vectorgiving 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 andinterval 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 ofdata depth, thenusing binary search to find a cutoffk such that an envelope containing thek% "deepest"curves also contains.width% of the curves, for each value of.width (note thatkand.width are not necessarily the same). This is in contrast to most functional boxplotor curve boxplot approaches, which tend to simply take the.width% deepest curves, andare generally quite conservative (i.e. they may contain more than.width% of the curves).

See Mirzargaret al. (2014) or Juulet al. (2020) for an accessible introductionto data depth and curve boxplots / functional boxplots.

Value

A data frame containing point summaries and intervals, with at least one column correspondingto the point summary, one to the lower end of the interval, one to the upper end of the interval, thewidth 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. Seevignette("lineribbon") for more examplesand discussion of the differences between pointwise and curvewise intervals.

Examples

library(dplyr)library(ggplot2)# generate a set of curvesk = 11 # number of curvesn = 201df = 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 intervalsdf %>%  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 eachelement 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 bedone more easily by mapping the.width orlevel computed variable toslab fill or color. SeeExamples.

Usage

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

Arguments

Value

Anordered factor of the same length asp giving the quantile interval towhich each value ofp belongs.

See Also

Seestat_slabinterval() andits shortcut stats, which generatecdf aesthetics that can be used withcut_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 = FALSEtibble(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 desiredtibble(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.

Supportsautomatic partial function application withwaived 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 ofstats::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 thex input argument.

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

• data.name: The deparsed name of thex input argument.

• has.na: AlwaysFALSE (for compatibility).

• cdf: Values of the (possibly weighted) empirical cumulative distributionfunction atx. Seeweighted_ecdf().

This allows existing methods for density objects, likeprint() andplot(), to work if desired.This output format (and in particular, thex andy components) is alsothe format expected by thedensity argument of thestat_slabinterval()and thesmooth_ 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 resamplingmethods.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.

Supportsautomatic partial function application withwaived 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 ofstats::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 thex input argument.

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

• data.name: The deparsed name of thex input argument.

• has.na: AlwaysFALSE (for compatibility).

• cdf: Values of the (possibly weighted) empirical cumulative distributionfunction atx. Seeweighted_ecdf().

This allows existing methods for density objects, likeprint() andplot(), to work if desired.This output format (and in particular, thex andy components) is alsothe format expected by thedensity argument of thestat_slabinterval()and thesmooth_ 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 usingstats::density().

Supportsautomatic partial function application withwaived 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 ofstats::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 thex input argument.

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

• data.name: The deparsed name of thex input argument.

• has.na: AlwaysFALSE (for compatibility).

• cdf: Values of the (possibly weighted) empirical cumulative distributionfunction atx. Seeweighted_ecdf().

This allows existing methods for density objects, likeprint() andplot(), to work if desired.This output format (and in particular, thex andy components) is alsothe format expected by thedensity argument of thestat_slabinterval()and thesmooth_ 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 thatthe 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 ofbins to find a bin width such that if the input data (x) is binnedusing a Wilkinson-style dotplot algorithm the height of the tallest binwill be less thanmaxheight.

This algorithm is used bygeom_dotsinterval() (and its variants) to automaticallyselect bin widths. Unless you are manually implementing you own dotplotgroborgeom, you probably do not need to use this function directly

Value

A suitable bin width such that a dotplot created with this bin widthandheightratio should have its tallest bin be less than or equal tomaxheight.

See Also

bin_dots() for an algorithm can bin dots using bin widths selectedby this function;geom_dotsinterval() for geometries that usethese algorithms to create dotplots.

Examples

library(dplyr)library(ggplot2)x = qnorm(ppoints(20))binwidth = find_dotplot_binwidth(x, maxheight = 4, heightratio = 1)binwidthbin_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 ofgeom_dots() for creating blurry dotplots. Accepts ansdaesthetic that gives the standard deviation of the blur applied to the dots.Requires a graphics engine supporting radial gradients. Unlikegeom_dots(),this geom only supports circular and squareshapes.

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

Thedots family of stats and geoms are similar toggplot2::geom_dotplot() but with a number of differences:

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

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

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

• The shape of the dots in these geoms can be changed using theslab_shape aesthetic (when using thedotsinterval family) or theshape orslab_shape aesthetic (when using thedots family)

Stats and geoms in this family include:

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

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

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

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

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

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

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

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

Value

Aggplot2::Geom representing a blurry dot geometry which canbe added to aggplot() object.

Aesthetics

The dots+intervalstats andgeoms have a wide variety of aesthetics that controlthe appearance of their three sub-geometries: thedots (aka theslab), thepoint, and theinterval.

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), thevalue of the data points themselves are used to determine stacking order. Only applies whenlayout is"bin" or"hex", as the other layout methods fully determine bothx andy positions.

• side: Which side to place the slab on."topright","top", and"right" are synonymswhich cause the slab to be drawn on the top or the right depending on iforientation is"horizontal"or"vertical"."bottomleft","bottom", and"left" are synonyms which cause the slabto be drawn on the bottom or the left depending on iforientation 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 bothsides (as in a violin plot).

• scale: What proportion of the region allocated to this geom to use to draw the slab. Ifscale = 1,slabs that use the maximum range will just touch each other. Default is0.9 to leave some spacebetween adjacent slabs. For a comprehensive discussion and examples of slab scaling and normalization,see thethickness scale article.

• justification: Justification of the interval relative to the slab, where0 indicates bottom/leftjustification and1 indicates top/right justification (depending onorientation). IfjustificationisNULL (the default), then it is set automatically based on the value ofside: whenside is"top"/"right"justification is set to0, whenside is"bottom"/"left"justification is set to1, and whenside is"both"justification is set to 0.5.

• datatype: When using composite geoms directly without astat (e.g.geom_slabinterval()),datatype is used toindicate which part of the geom a row in the data targets: rows withdatatype = "slab" target theslab portion of the geometry and rows withdatatype = "interval" target the interval portion ofthe geometry. This is set automatically when using ggdiststats.

Interval-specific aesthetics

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

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

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

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

Point-specific aesthetics

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

Color aesthetics

• colour: (orcolor) The color of theinterval andpoint sub-geometries.Use theslab_color,interval_color, orpoint_color aesthetics (below) toset sub-geometry colors separately.

• fill: The fill color of theslab andpoint sub-geometries. Use theslab_fillorpoint_fill aesthetics (below) to set sub-geometry colors separately.

• alpha: The opacity of theslab,interval, andpoint sub-geometries. Use theslab_alpha,interval_alpha, orpoint_alpha aesthetics (below) to set sub-geometry colors separately.

• colour_ramp: (orcolor_ramp) A secondary scale that modifies thecolorscale to "ramp" to another color. Seescale_colour_ramp() for examples.

• fill_ramp: A secondary scale that modifies thefillscale to "ramp" to another color. Seescale_fill_ramp() for examples.

Line aesthetics

• linewidth: Width of the line used to draw theinterval (except withgeom_slab(): thenit is the width of theslab). With composite geometries including an interval and slab,useslab_linewidth to set the line width of theslab (see below). Forinterval, rawlinewidth values are transformed according to theinterval_size_domain andinterval_size_rangeparameters of thegeom (see above).

• size: Determines the size of thepoint. Iflinewidth is not provided,size willalso determines the width of the line used to draw theinterval (this allows line width andpoint size to be modified together by setting onlysize and notlinewidth). Rawsize values are transformed according to theinterval_size_domain,interval_size_range,andfatten_point parameters of thegeom (see above). Use thepoint_size aesthetic(below) to set sub-geometry size directly without applying the effects ofinterval_size_domain,interval_size_range, andfatten_point.

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

• linetype: Type of line (e.g.,"solid","dashed", etc) used to draw theintervaland the outline of theslab (if it is visible). Use theslab_linetype orinterval_linetype aesthetics (below) to set sub-geometry line types separately.

Slab-specific color and line override aesthetics

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

• slab_colour: (orslab_color) Override forcolour/color: the outline color of the slab.

• slab_alpha: Override foralpha: the opacity of the slab.

• slab_linewidth: Override forlinwidth: the width of the outline of the slab.

• slab_linetype: Override forlinetype: the line type of the outline of the slab.

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

Interval-specific color and line override aesthetics

• interval_colour: (orinterval_color) Override forcolour/color: the color of the interval.

• interval_alpha: Override foralpha: the opacity of the interval.

• interval_linetype: Override forlinetype: the line type of the interval.

Point-specific color and line override aesthetics

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

• point_colour: (orpoint_color) Override forcolour/color: the outline color of the point.

• point_alpha: Override foralpha: the opacity of the point.

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

Deprecated aesthetics

• slab_size: Useslab_linewidth.

• interval_size: Useinterval_linewidth.

Other aesthetics (these work as in standardgeoms)

• width

• height

• group

See examples of some of these aesthetics in action invignette("dotsinterval").Learn more about the sub-geom override aesthetics (likeinterval_color) in thescales documentation. Learn more about basic ggplot aesthetics invignette("ggplot2-specs").

References

Kay, M., Kola, T., Hullman, J. R., & Munson, S. A. (2016). When (ish) is My Bus? User-centered Visualizationsof Uncertainty in Everyday, Mobile Predictive Systems.Conference on Human Factorsin 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 Dotplotsor CDFs Improve Transit Decision-Making.Conference on Human Factors in Computing Systems - CHI '18.doi:10.1145/3173574.3173718.

See Also

Seegeom_dotsinterval() for the geometry this shortcut is based on.

Seevignette("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 ofgeom_dotsinterval() for creating dot plots.Geoms based ongeom_dotsinterval() create dotplots that automaticallyensure 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

Thedots family of stats and geoms are similar toggplot2::geom_dotplot() but with a number of differences:

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

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

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

• The shape of the dots in these geoms can be changed using theslab_shape aesthetic (when using thedotsinterval family) or theshape orslab_shape aesthetic (when using thedots family)

Stats and geoms in this family include:

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

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

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

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

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

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

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

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

Value

Aggplot2::Geom representing a dot geometry which canbe added to aggplot() object.

Aesthetics

The dots+intervalstats andgeoms have a wide variety of aesthetics that controlthe appearance of their three sub-geometries: thedots (aka theslab), thepoint, and theinterval.

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), thevalue of the data points themselves are used to determine stacking order. Only applies whenlayout is"bin" or"hex", as the other layout methods fully determine bothx andy positions.

• side: Which side to place the slab on."topright","top", and"right" are synonymswhich cause the slab to be drawn on the top or the right depending on iforientation is"horizontal"or"vertical"."bottomleft","bottom", and"left" are synonyms which cause the slabto be drawn on the bottom or the left depending on iforientation 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 bothsides (as in a violin plot).

• scale: What proportion of the region allocated to this geom to use to draw the slab. Ifscale = 1,slabs that use the maximum range will just touch each other. Default is0.9 to leave some spacebetween adjacent slabs. For a comprehensive discussion and examples of slab scaling and normalization,see thethickness scale article.

• justification: Justification of the interval relative to the slab, where0 indicates bottom/leftjustification and1 indicates top/right justification (depending onorientation). IfjustificationisNULL (the default), then it is set automatically based on the value ofside: whenside is"top"/"right"justification is set to0, whenside is"bottom"/"left"justification is set to1, and whenside is"both"justification is set to 0.5.

• datatype: When using composite geoms directly without astat (e.g.geom_slabinterval()),datatype is used toindicate which part of the geom a row in the data targets: rows withdatatype = "slab" target theslab portion of the geometry and rows withdatatype = "interval" target the interval portion ofthe geometry. This is set automatically when using ggdiststats.

Interval-specific aesthetics

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

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

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

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

Point-specific aesthetics

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

Color aesthetics

• colour: (orcolor) The color of theinterval andpoint sub-geometries.Use theslab_color,interval_color, orpoint_color aesthetics (below) toset sub-geometry colors separately.

• fill: The fill color of theslab andpoint sub-geometries. Use theslab_fillorpoint_fill aesthetics (below) to set sub-geometry colors separately.

• alpha: The opacity of theslab,interval, andpoint sub-geometries. Use theslab_alpha,interval_alpha, orpoint_alpha aesthetics (below) to set sub-geometry colors separately.

• colour_ramp: (orcolor_ramp) A secondary scale that modifies thecolorscale to "ramp" to another color. Seescale_colour_ramp() for examples.

• fill_ramp: A secondary scale that modifies thefillscale to "ramp" to another color. Seescale_fill_ramp() for examples.

Line aesthetics

• linewidth: Width of the line used to draw theinterval (except withgeom_slab(): thenit is the width of theslab). With composite geometries including an interval and slab,useslab_linewidth to set the line width of theslab (see below). Forinterval, rawlinewidth values are transformed according to theinterval_size_domain andinterval_size_rangeparameters of thegeom (see above).

• size: Determines the size of thepoint. Iflinewidth is not provided,size willalso determines the width of the line used to draw theinterval (this allows line width andpoint size to be modified together by setting onlysize and notlinewidth). Rawsize values are transformed according to theinterval_size_domain,interval_size_range,andfatten_point parameters of thegeom (see above). Use thepoint_size aesthetic(below) to set sub-geometry size directly without applying the effects ofinterval_size_domain,interval_size_range, andfatten_point.

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

• linetype: Type of line (e.g.,"solid","dashed", etc) used to draw theintervaland the outline of theslab (if it is visible). Use theslab_linetype orinterval_linetype aesthetics (below) to set sub-geometry line types separately.

Slab-specific color and line override aesthetics

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

• slab_colour: (orslab_color) Override forcolour/color: the outline color of the slab.

• slab_alpha: Override foralpha: the opacity of the slab.

• slab_linewidth: Override forlinwidth: the width of the outline of the slab.

• slab_linetype: Override forlinetype: the line type of the outline of the slab.

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

Interval-specific color and line override aesthetics

• interval_colour: (orinterval_color) Override forcolour/color: the color of the interval.

• interval_alpha: Override foralpha: the opacity of the interval.

• interval_linetype: Override forlinetype: the line type of the interval.

Point-specific color and line override aesthetics

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

• point_colour: (orpoint_color) Override forcolour/color: the outline color of the point.

• point_alpha: Override foralpha: the opacity of the point.

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

Deprecated aesthetics

• slab_size: Useslab_linewidth.

• interval_size: Useinterval_linewidth.

Other aesthetics (these work as in standardgeoms)

• width

• height

• group

See examples of some of these aesthetics in action invignette("dotsinterval").Learn more about the sub-geom override aesthetics (likeinterval_color) in thescales documentation. Learn more about basic ggplot aesthetics invignette("ggplot2-specs").

References

Kay, M., Kola, T., Hullman, J. R., & Munson, S. A. (2016). When (ish) is My Bus? User-centered Visualizationsof Uncertainty in Everyday, Mobile Predictive Systems.Conference on Human Factorsin 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 Dotplotsor CDFs Improve Transit Decision-Making.Conference on Human Factors in Computing Systems - CHI '18.doi:10.1145/3173574.3173718.

See Also

Seestat_dots() for the stat version, intended foruse on sample data or analytical distributions.

Seegeom_dotsinterval() for the geometry this shortcut is based on.

Seevignette("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 discretedf %>%  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 ongeom_dotsinterval() create dotplots that automatically determine a bin width thatensures the plot fits within the available space. They also ensure dots do not overlap, and allowthe generation of quantile dotplots using thequantiles argument tostat_dotsinterval()/stat_dots().Generally follows the naming scheme andarguments of thegeom_slabinterval() andstat_slabinterval() family ofgeoms 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

Thedots family of stats and geoms are similar toggplot2::geom_dotplot() but with a number of differences:

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

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

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

• The shape of the dots in these geoms can be changed using theslab_shape aesthetic (when using thedotsinterval family) or theshape orslab_shape aesthetic (when using thedots family)

Stats and geoms in this family include:

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

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

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

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

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

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

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

stat_dots() andstat_dotsinterval(), when used with thequantiles argument,are particularly useful for constructing quantile dotplots, which can be an effective way to communicate uncertaintyusing 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 abootstrap distribution, or a Bayesian posterior, you can supply samples tothex ory aesthetic.

To visualize analytical distributions, you can use thexdist orydistaesthetic. For historical reasons, you can also usedist to specify the distribution, thoughthis is not recommended as it does not work as well with orientation detection.These aesthetics can be used as follows:

• xdist,ydist, anddist can be any distribution object from thedistributionalpackage (dist_normal(),dist_beta(), etc)or can be aposterior::rvar() object. Since these functions are vectorized,other columns can be passed directly to them in anaes() specification; e.g.aes(dist = dist_normal(mu, sigma)) will work ifmu andsigma are columns in theinput data frame.

• dist can be a character vector giving the distribution name. Then thearg1, ...arg9aesthetics (orargs as a list column) specify distribution arguments. Distribution namesshould correspond to R functions that have"p","q", and"d" functions; e.g."norm"is a valid distribution name because R defines thepnorm(),qnorm(), anddnorm()functions for Normal distributions.

  See theparse_dist() function for a useful way to generatedist andargsvalues from human-readable distribution specs (like"normal(0,1)"). Such specs are alsoproduced by other packages (like thebrms::get_prior function in brms); thus,parse_dist() combined with the stats described here can help you visualize the outputof those functions.

Value

Aggplot2::Geom orggplot2::Stat representing a dotplot or combined dotplot+interval geometry which canbe added to aggplot() object.

Aesthetics

The dots+intervalstats andgeoms have a wide variety of aesthetics that controlthe appearance of their three sub-geometries: thedots (aka theslab), thepoint, and theinterval.

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), thevalue of the data points themselves are used to determine stacking order. Only applies whenlayout is"bin" or"hex", as the other layout methods fully determine bothx andy positions.

• side: Which side to place the slab on."topright","top", and"right" are synonymswhich cause the slab to be drawn on the top or the right depending on iforientation is"horizontal"or"vertical"."bottomleft","bottom", and"left" are synonyms which cause the slabto be drawn on the bottom or the left depending on iforientation 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 bothsides (as in a violin plot).

• scale: What proportion of the region allocated to this geom to use to draw the slab. Ifscale = 1,slabs that use the maximum range will just touch each other. Default is0.9 to leave some spacebetween adjacent slabs. For a comprehensive discussion and examples of slab scaling and normalization,see thethickness scale article.

• justification: Justification of the interval relative to the slab, where0 indicates bottom/leftjustification and1 indicates top/right justification (depending onorientation). IfjustificationisNULL (the default), then it is set automatically based on the value ofside: whenside is"top"/"right"justification is set to0, whenside is"bottom"/"left"justification is set to1, and whenside is"both"justification is set to 0.5.

• datatype: When using composite geoms directly without astat (e.g.geom_slabinterval()),datatype is used toindicate which part of the geom a row in the data targets: rows withdatatype = "slab" target theslab portion of the geometry and rows withdatatype = "interval" target the interval portion ofthe geometry. This is set automatically when using ggdiststats.

Interval-specific aesthetics

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

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

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

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

Point-specific aesthetics

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

Color aesthetics

• colour: (orcolor) The color of theinterval andpoint sub-geometries.Use theslab_color,interval_color, orpoint_color aesthetics (below) toset sub-geometry colors separately.

• fill: The fill color of theslab andpoint sub-geometries. Use theslab_fillorpoint_fill aesthetics (below) to set sub-geometry colors separately.

• alpha: The opacity of theslab,interval, andpoint sub-geometries. Use theslab_alpha,interval_alpha, orpoint_alpha aesthetics (below) to set sub-geometry colors separately.

• colour_ramp: (orcolor_ramp) A secondary scale that modifies thecolorscale to "ramp" to another color. Seescale_colour_ramp() for examples.

• fill_ramp: A secondary scale that modifies thefillscale to "ramp" to another color. Seescale_fill_ramp() for examples.

Line aesthetics

• linewidth: Width of the line used to draw theinterval (except withgeom_slab(): thenit is the width of theslab). With composite geometries including an interval and slab,useslab_linewidth to set the line width of theslab (see below). Forinterval, rawlinewidth values are transformed according to theinterval_size_domain andinterval_size_rangeparameters of thegeom (see above).

• size: Determines the size of thepoint. Iflinewidth is not provided,size willalso determines the width of the line used to draw theinterval (this allows line width andpoint size to be modified together by setting onlysize and notlinewidth). Rawsize values are transformed according to theinterval_size_domain,interval_size_range,andfatten_point parameters of thegeom (see above). Use thepoint_size aesthetic(below) to set sub-geometry size directly without applying the effects ofinterval_size_domain,interval_size_range, andfatten_point.

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

• linetype: Type of line (e.g.,"solid","dashed", etc) used to draw theintervaland the outline of theslab (if it is visible). Use theslab_linetype orinterval_linetype aesthetics (below) to set sub-geometry line types separately.

Slab-specific color and line override aesthetics

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

• slab_colour: (orslab_color) Override forcolour/color: the outline color of the slab.

• slab_alpha: Override foralpha: the opacity of the slab.

• slab_linewidth: Override forlinwidth: the width of the outline of the slab.

• slab_linetype: Override forlinetype: the line type of the outline of the slab.

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

Interval-specific color and line override aesthetics

• interval_colour: (orinterval_color) Override forcolour/color: the color of the interval.

• interval_alpha: Override foralpha: the opacity of the interval.

• interval_linetype: Override forlinetype: the line type of the interval.

Point-specific color and line override aesthetics

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

• point_colour: (orpoint_color) Override forcolour/color: the outline color of the point.

• point_alpha: Override foralpha: the opacity of the point.

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

Deprecated aesthetics

• slab_size: Useslab_linewidth.

• interval_size: Useinterval_linewidth.

Other aesthetics (these work as in standardgeoms)

• width

• height

• group

See examples of some of these aesthetics in action invignette("dotsinterval").Learn more about the sub-geom override aesthetics (likeinterval_color) in thescales documentation. Learn more about basic ggplot aesthetics invignette("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 Visualizationsof Uncertainty in Everyday, Mobile Predictive Systems.Conference on Human Factorsin 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 Dotplotsor CDFs Improve Transit Decision-Making.Conference on Human Factors in Computing Systems - CHI '18.doi:10.1145/3173574.3173718.

See Also

See thestat_slabinterval() family for otherstats built on top ofgeom_slabinterval().Seevignette("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 discretedf %>%  ggplot(aes(x = value, y = g)) +  geom_dotsinterval()df %>%  ggplot(aes(y = value, x = g)) +  geom_dotsinterval()# stat_dots can summarize quantiles, creating quantile dotplotsdata(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 intervalRankCorr_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 ofgeom_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 wrapsgeom_slabinterval() with defaults designed to producemultiple-interval plots. Default aesthetic mappings are applied if the.width columnis present in the input data (e.g., as generated by thepoint_interval() family of functions),making this geom often more convenient than vanillaggplot2 geometries when used withfunctions likemedian_qi(),mean_qi(),mode_hdi(), etc.

Specifically, if.width is present in the input,geom_interval() actsas if its default aesthetics areaes(colour = forcats::fct_rev(ordered(.width)))

Value

Aggplot2::Geom representing a multiple-interval geometry which canbe added to aggplot() object.

Aesthetics

The slab+intervalstats andgeoms have a wide variety of aesthetics that controlthe appearance of their three sub-geometries: theslab, thepoint, andtheinterval.

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

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

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

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

Color aesthetics

• colour: (orcolor) The color of theinterval andpoint sub-geometries.Use theslab_color,interval_color, orpoint_color aesthetics (below) toset sub-geometry colors separately.

• fill: The fill color of theslab andpoint sub-geometries. Use theslab_fillorpoint_fill aesthetics (below) to set sub-geometry colors separately.

• alpha: The opacity of theslab,interval, andpoint sub-geometries. Use theslab_alpha,interval_alpha, orpoint_alpha aesthetics (below) to set sub-geometry colors separately.

• colour_ramp: (orcolor_ramp) A secondary scale that modifies thecolorscale to "ramp" to another color. Seescale_colour_ramp() for examples.

• fill_ramp: A secondary scale that modifies thefillscale to "ramp" to another color. Seescale_fill_ramp() for examples.

Line aesthetics

• linewidth: Width of the line used to draw theinterval (except withgeom_slab(): thenit is the width of theslab). With composite geometries including an interval and slab,useslab_linewidth to set the line width of theslab (see below). Forinterval, rawlinewidth values are transformed according to theinterval_size_domain andinterval_size_rangeparameters of thegeom (see above).

• size: Determines the size of thepoint. Iflinewidth is not provided,size willalso determines the width of the line used to draw theinterval (this allows line width andpoint size to be modified together by setting onlysize and notlinewidth). Rawsize values are transformed according to theinterval_size_domain,interval_size_range,andfatten_point parameters of thegeom (see above). Use thepoint_size aesthetic(below) to set sub-geometry size directly without applying the effects ofinterval_size_domain,interval_size_range, andfatten_point.

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

• linetype: Type of line (e.g.,"solid","dashed", etc) used to draw theintervaland the outline of theslab (if it is visible). Use theslab_linetype orinterval_linetype aesthetics (below) to set sub-geometry line types separately.

Interval-specific color and line override aesthetics

• interval_colour: (orinterval_color) Override forcolour/color: the color of the interval.

• interval_alpha: Override foralpha: the opacity of the interval.

• interval_linetype: Override forlinetype: the line type of the interval.

Deprecated aesthetics

• interval_size: Useinterval_linewidth.

Other aesthetics (these work as in standardgeoms)

• width

• height

• group

See examples of some of these aesthetics in action invignette("slabinterval").Learn more about the sub-geom override aesthetics (likeinterval_color) in thescales documentation. Learn more about basic ggplot aesthetics invignette("ggplot2-specs").

See Also

Seestat_interval() for the stat version, intended foruse on sample data or analytical distributions.Seegeom_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/ymaxRankCorr_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 ofgeom_line() andgeom_ribbon()with default aesthetics designed for use with output frompoint_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 ageom_line() andgeom_ribbon() designed for use with output frompoint_interval().This geom sets some default aesthetics equal to the.width column generated by thepoint_interval() family of functions, making them often more convenient than a vanillageom_ribbon() +geom_line().

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

Value

Aggplot2::Geom representing a combined line + multiple-ribbon geometry which canbe added to aggplot() object.

Aesthetics

The line+ribbonstats andgeoms have a wide variety of aesthetics that controlthe appearance of their two sub-geometries: theline and theribbon.

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

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

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

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

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

Color aesthetics

• colour: (orcolor) The color of theline sub-geometry.

• fill: The fill color of theribbon sub-geometry.

• alpha: The opacity of theline andribbon sub-geometries.

• fill_ramp: A secondary scale that modifies thefillscale to "ramp" to another color. Seescale_fill_ramp() for examples.

Line aesthetics

• linewidth: Width ofline. Inggplot2 < 3.4, was calledsize.

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

Other aesthetics (these work as in standardgeoms)

• group

See examples of some of these aesthetics in action invignette("lineribbon").Learn more about the sub-geom override aesthetics (likeinterval_color) in thescales documentation. Learn more about basic ggplot aesthetics invignette("ggplot2-specs").

Author(s)

Matthew Kay

See Also

Seestat_lineribbon() for a version that does summarizing of samples into points and intervalswithin ggplot. Seegeom_pointinterval() for a similar geom intendedfor point summaries and intervals. Seegeom_line() andgeom_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 ofgeom_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 wrapsgeom_slabinterval() with defaults designed to producepoint + multiple-interval plots. Default aesthetic mappings are applied if the.width columnis present in the input data (e.g., as generated by thepoint_interval() family of functions),making this geom often more convenient than vanillaggplot2 geometries when used withfunctions likemedian_qi(),mean_qi(),mode_hdi(), etc.

Specifically, if.width is present in the input,geom_pointinterval() actsas if its default aesthetics areaes(size = -.width)

Value

Aggplot2::Geom representing a point + multiple-interval geometry which canbe added to aggplot() object.

Aesthetics

The slab+intervalstats andgeoms have a wide variety of aesthetics that controlthe appearance of their three sub-geometries: theslab, thepoint, andtheinterval.

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

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

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

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

Point-specific aesthetics

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

Color aesthetics

• colour: (orcolor) The color of theinterval andpoint sub-geometries.Use theslab_color,interval_color, orpoint_color aesthetics (below) toset sub-geometry colors separately.

• fill: The fill color of theslab andpoint sub-geometries. Use theslab_fillorpoint_fill aesthetics (below) to set sub-geometry colors separately.

• alpha: The opacity of theslab,interval, andpoint sub-geometries. Use theslab_alpha,interval_alpha, orpoint_alpha aesthetics (below) to set sub-geometry colors separately.

• colour_ramp: (orcolor_ramp) A secondary scale that modifies thecolorscale to "ramp" to another color. Seescale_colour_ramp() for examples.

• fill_ramp: A secondary scale that modifies thefillscale to "ramp" to another color. Seescale_fill_ramp() for examples.

Line aesthetics

• linewidth: Width of the line used to draw theinterval (except withgeom_slab(): thenit is the width of theslab). With composite geometries including an interval and slab,useslab_linewidth to set the line width of theslab (see below). Forinterval, rawlinewidth values are transformed according to theinterval_size_domain andinterval_size_rangeparameters of thegeom (see above).

• size: Determines the size of thepoint. Iflinewidth is not provided,size willalso determines the width of the line used to draw theinterval (this allows line width andpoint size to be modified together by setting onlysize and notlinewidth). Rawsize values are transformed according to theinterval_size_domain,interval_size_range,andfatten_point parameters of thegeom (see above). Use thepoint_size aesthetic(below) to set sub-geometry size directly without applying the effects ofinterval_size_domain,interval_size_range, andfatten_point.

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

• linetype: Type of line (e.g.,"solid","dashed", etc) used to draw theintervaland the outline of theslab (if it is visible). Use theslab_linetype orinterval_linetype aesthetics (below) to set sub-geometry line types separately.

Interval-specific color and line override aesthetics

• interval_colour: (orinterval_color) Override forcolour/color: the color of the interval.

• interval_alpha: Override foralpha: the opacity of the interval.

• interval_linetype: Override forlinetype: the line type of the interval.

Point-specific color and line override aesthetics

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

• point_colour: (orpoint_color) Override forcolour/color: the outline color of the point.

• point_alpha: Override foralpha: the opacity of the point.

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

Deprecated aesthetics

• interval_size: Useinterval_linewidth.

Other aesthetics (these work as in standardgeoms)

• width

• height

• group

See examples of some of these aesthetics in action invignette("slabinterval").Learn more about the sub-geom override aesthetics (likeinterval_color) in thescales documentation. Learn more about basic ggplot aesthetics invignette("ggplot2-specs").

See Also

Seestat_pointinterval() for the stat version, intended foruse on sample data or analytical distributions.Seegeom_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/ymaxRankCorr_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 ofgeom_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

Aggplot2::Geom representing a slab (ridge) geometry which canbe added to aggplot() object.

Aesthetics

The slab+intervalstats andgeoms have a wide variety of aesthetics that controlthe appearance of their three sub-geometries: theslab, thepoint, andtheinterval.

Positional aesthetics

• x: x position of the geometry

• y: y position of the geometry

Slab-specific aesthetics

• thickness: The thickness of the slab at eachx value (iforientation = "horizontal") ory value (iforientation = "vertical") of the slab.

• side: Which side to place the slab on."topright","top", and"right" are synonymswhich cause the slab to be drawn on the top or the right depending on iforientation is"horizontal"or"vertical"."bottomleft","bottom", and"left" are synonyms which cause the slabto be drawn on the bottom or the left depending on iforientation 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 bothsides (as in a violin plot).

• scale: What proportion of the region allocated to this geom to use to draw the slab. Ifscale = 1,slabs that use the maximum range will just touch each other. Default is0.9 to leave some spacebetween adjacent slabs. For a comprehensive discussion and examples of slab scaling and normalization,see thethickness scale article.

• justification: Justification of the interval relative to the slab, where0 indicates bottom/leftjustification and1 indicates top/right justification (depending onorientation). IfjustificationisNULL (the default), then it is set automatically based on the value ofside: whenside is"top"/"right"justification is set to0, whenside is"bottom"/"left"justification is set to1, and whenside is"both"justification is set to 0.5.

Color aesthetics

• colour: (orcolor) The color of theinterval andpoint sub-geometries.Use theslab_color,interval_color, orpoint_color aesthetics (below) toset sub-geometry colors separately.

• fill: The fill color of theslab andpoint sub-geometries. Use theslab_fillorpoint_fill aesthetics (below) to set sub-geometry colors separately.

• alpha: The opacity of theslab,interval, andpoint sub-geometries. Use theslab_alpha,interval_alpha, orpoint_alpha aesthetics (below) to set sub-geometry colors separately.

• colour_ramp: (orcolor_ramp) A secondary scale that modifies thecolorscale to "ramp" to another color. Seescale_colour_ramp() for examples.

• fill_ramp: A secondary scale that modifies thefillscale to "ramp" to another color. Seescale_fill_ramp() for examples.

Line aesthetics

• linewidth: Width of the line used to draw theinterval (except withgeom_slab(): thenit is the width of theslab). With composite geometries including an interval and slab,useslab_linewidth to set the line width of theslab (see below). Forinterval, rawlinewidth values are transformed according to theinterval_size_domain andinterval_size_rangeparameters of thegeom (see above).

• size: Determines the size of thepoint. Iflinewidth is not provided,size willalso determines the width of the line used to draw theinterval (this allows line width andpoint size to be modified together by setting onlysize and notlinewidth). Rawsize values are transformed according to theinterval_size_domain,interval_size_range,andfatten_point parameters of thegeom (see above). Use thepoint_size aesthetic(below) to set sub-geometry size directly without applying the effects ofinterval_size_domain,interval_size_range, andfatten_point.

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

• linetype: Type of line (e.g.,"solid","dashed", etc) used to draw theintervaland the outline of theslab (if it is visible). Use theslab_linetype orinterval_linetype aesthetics (below) to set sub-geometry line types separately.

Slab-specific color and line override aesthetics

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

• slab_colour: (orslab_color) Override forcolour/color: the outline color of the slab.

• slab_alpha: Override foralpha: the opacity of the slab.

• slab_linewidth: Override forlinwidth: the width of the outline of the slab.

• slab_linetype: Override forlinetype: the line type of the outline of the slab.

Deprecated aesthetics

• slab_size: Useslab_linewidth.

Other aesthetics (these work as in standardgeoms)

• width

• height

• group

See examples of some of these aesthetics in action invignette("slabinterval").Learn more about the sub-geom override aesthetics (likeinterval_color) in thescales documentation. Learn more about basic ggplot aesthetics invignette("ggplot2-specs").

See Also

Seestat_slab() for the stat version, intended foruse on sample data or analytical distributions.Seegeom_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 transformationsdf = 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 ydf %>%  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 colordf %>%  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, andintervals. It acts as a meta-geom for many otherggdist geoms that are wrappers around this geom, includingeye plots, half-eye plots, CCDF barplots, and point+multiple interval plots, and supports both horizontal andvertical orientations, dodging (via theposition argument), and relative justification of slabs with theircorresponding 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 touse the shortcut geoms instead as they create more useful mnemonic primitives, such as eye plots,half-eye plots, point+interval plots, or CCDF barplots.

Theslab portion of the geom is much like a ridge or "joy" plot: it represents the value of a functionscaled to fit between values on thex ory axis (depending on the value oforientation). Values ofthe functions are specified using thethickness aesthetic and are scaled to fit intoscaletimes the distance between points on the relevant axis. E.g., iforientation is"horizontal",scale is0.9, andy is a discrete variable, then thethickness aesthetic specifies thevalue of some function ofx that is drawn for everyy value and scaled to fit into0.9 timesthe distance between points on they axis.

For theinterval portion of the geom,x andy aesthetics specify the location of thepoint, andymin/ymax orxmin/xmax (depending on the value oforientation)specify the endpoints of the interval. A scaling factor for interval line width and point size is appliedthrough theinterval_size_domain,interval_size_range, andfatten_point parameters.These scaling factors are designed to give multiple uncertainty intervals reasonablescaling at the default settings forscale_size_continuous().

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

Wrapper geoms include:

• geom_pointinterval()

• geom_interval()

• geom_slab()

In addition, thestat_slabinterval() family of stats uses geoms from thegeom_slabinterval() family, and is often easier to use than using these geomsdirectly. 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

Aggplot2::Geom representing a slab or combined slab+interval geometry which canbe added to aggplot() object.

Aesthetics

The slab+intervalstats andgeoms have a wide variety of aesthetics that controlthe appearance of their three sub-geometries: theslab, thepoint, andtheinterval.

Positional aesthetics

• x: x position of the geometry

• y: y position of the geometry

Slab-specific aesthetics

• thickness: The thickness of the slab at eachx value (iforientation = "horizontal") ory value (iforientation = "vertical") of the slab.

• side: Which side to place the slab on."topright","top", and"right" are synonymswhich cause the slab to be drawn on the top or the right depending on iforientation is"horizontal"or"vertical"."bottomleft","bottom", and"left" are synonyms which cause the slabto be drawn on the bottom or the left depending on iforientation 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 bothsides (as in a violin plot).

• scale: What proportion of the region allocated to this geom to use to draw the slab. Ifscale = 1,slabs that use the maximum range will just touch each other. Default is0.9 to leave some spacebetween adjacent slabs. For a comprehensive discussion and examples of slab scaling and normalization,see thethickness scale article.

• justification: Justification of the interval relative to the slab, where0 indicates bottom/leftjustification and1 indicates top/right justification (depending onorientation). IfjustificationisNULL (the default), then it is set automatically based on the value ofside: whenside is"top"/"right"justification is set to0, whenside is"bottom"/"left"justification is set to1, and whenside is"both"justification is set to 0.5.

• datatype: When using composite geoms directly without astat (e.g.geom_slabinterval()),datatype is used toindicate which part of the geom a row in the data targets: rows withdatatype = "slab" target theslab portion of the geometry and rows withdatatype = "interval" target the interval portion ofthe geometry. This is set automatically when using ggdiststats.

Interval-specific aesthetics

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

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

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

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

Point-specific aesthetics

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

Color aesthetics

• colour: (orcolor) The color of theinterval andpoint sub-geometries.Use theslab_color,interval_color, orpoint_color aesthetics (below) toset sub-geometry colors separately.

• fill: The fill color of theslab andpoint sub-geometries. Use theslab_fillorpoint_fill aesthetics (below) to set sub-geometry colors separately.

• alpha: The opacity of theslab,interval, andpoint sub-geometries. Use theslab_alpha,interval_alpha, orpoint_alpha aesthetics (below) to set sub-geometry colors separately.

• colour_ramp: (orcolor_ramp) A secondary scale that modifies thecolorscale to "ramp" to another color. Seescale_colour_ramp() for examples.

• fill_ramp: A secondary scale that modifies thefillscale to "ramp" to another color. Seescale_fill_ramp() for examples.

Line aesthetics

• linewidth: Width of the line used to draw theinterval (except withgeom_slab(): thenit is the width of theslab). With composite geometries including an interval and slab,useslab_linewidth to set the line width of theslab (see below). Forinterval, rawlinewidth values are transformed according to theinterval_size_domain andinterval_size_rangeparameters of thegeom (see above).

• size: Determines the size of thepoint. Iflinewidth is not provided,size willalso determines the width of the line used to draw theinterval (this allows line width andpoint size to be modified together by setting onlysize and notlinewidth). Rawsize values are transformed according to theinterval_size_domain,interval_size_range,andfatten_point parameters of thegeom (see above). Use thepoint_size aesthetic(below) to set sub-geometry size directly without applying the effects ofinterval_size_domain,interval_size_range, andfatten_point.

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

• linetype: Type of line (e.g.,"solid","dashed", etc) used to draw theintervaland the outline of theslab (if it is visible). Use theslab_linetype orinterval_linetype aesthetics (below) to set sub-geometry line types separately.

Slab-specific color and line override aesthetics

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

• slab_colour: (orslab_color) Override forcolour/color: the outline color of the slab.

• slab_alpha: Override foralpha: the opacity of the slab.

• slab_linewidth: Override forlinwidth: the width of the outline of the slab.

• slab_linetype: Override forlinetype: the line type of the outline of the slab.

Interval-specific color and line override aesthetics

• interval_colour: (orinterval_color) Override forcolour/color: the color of the interval.

• interval_alpha: Override foralpha: the opacity of the interval.

• interval_linetype: Override forlinetype: the line type of the interval.

Point-specific color and line override aesthetics

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

• point_colour: (orpoint_color) Override forcolour/color: the outline color of the point.

• point_alpha: Override foralpha: the opacity of the point.

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

Deprecated aesthetics

• slab_size: Useslab_linewidth.

• interval_size: Useinterval_linewidth.

Other aesthetics (these work as in standardgeoms)

• width

• height

• group

See examples of some of these aesthetics in action invignette("slabinterval").Learn more about the sub-geom override aesthetics (likeinterval_color) in thescales documentation. Learn more about basic ggplot aesthetics invignette("ggplot2-specs").

Author(s)

Matthew Kay

See Also

Seegeom_lineribbon() for a combination geom designed for fit curves plus probability bands.Seegeom_dotsinterval() for a combination geom designed for plotting dotplots with intervals.Seestat_slabinterval() for families of statsbuilt on top of this geom for common use cases (likestat_halfeye()).Seevignette("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 ofgeom_slabinterval() geometries: this geometry understands the scaling andpositioning of thethickness aesthetic fromgeom_slabinterval(), whichallows 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 thethickness aestheticto determine where the endpoint of the line is, which allows it to be usedwithgeom_slabinterval() geometries for labeling specific values of thethickness function.

Value

Aggplot2::Geom representing a spike geometry which canbe added to aggplot() object.rd_slabinterval_aesthetics(geom_name),

Aesthetics

The spikegeom has a wide variety of aesthetics that controlthe appearance of its two sub-geometries: thespike and thepoint.

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 eachx value (iforientation = "horizontal") ory value (iforientation = "vertical") of the slab.

• side: Which side to place the slab on."topright","top", and"right" are synonymswhich cause the slab to be drawn on the top or the right depending on iforientation is"horizontal"or"vertical"."bottomleft","bottom", and"left" are synonyms which cause the slabto be drawn on the bottom or the left depending on iforientation 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 bothsides (as in a violin plot).

• scale: What proportion of the region allocated to this geom to use to draw the slab. Ifscale = 1,slabs that use the maximum range will just touch each other. Default is0.9 to leave some spacebetween adjacent slabs. For a comprehensive discussion and examples of slab scaling and normalization,see thethickness scale article.

Color aesthetics

• colour: (orcolor) The color of thespike andpoint sub-geometries.

• fill: The fill color of thepoint sub-geometry.

• alpha: The opacity of thespike andpoint sub-geometries.

• colour_ramp: (orcolor_ramp) A secondary scale that modifies thecolorscale to "ramp" to another color. Seescale_colour_ramp() for examples.

• fill_ramp: A secondary scale that modifies thefillscale to "ramp" to another color. Seescale_fill_ramp() for examples.

Line aesthetics

• linewidth: Width of the line used to draw thespike sub-geometry.

• size: Size of thepoint sub-geometry.

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

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

Other aesthetics (these work as in standardgeoms)

• width

• height

• group

See examples of some of these aesthetics in action invignette("slabinterval").Learn more about the sub-geom override aesthetics (likeinterval_color) in thescales documentation. Learn more about basic ggplot aesthetics invignette("ggplot2-specs").

See Also

Seestat_spike() for the stat version, intended foruse 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 objectsdf = tibble(  d = dist_normal(1:2, 1:2), g = c("a", "b"))# annotate the density at the mean of a distributiondf %>% 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 = 0arrow_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 ofgeom_dotsinterval() for creating beeswarm plots.Geoms based ongeom_dotsinterval() create dotplots that automaticallyensure 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

Thedots family of stats and geoms are similar toggplot2::geom_dotplot() but with a number of differences:

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

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

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

• The shape of the dots in these geoms can be changed using theslab_shape aesthetic (when using thedotsinterval family) or theshape orslab_shape aesthetic (when using thedots family)

Stats and geoms in this family include:

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

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

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

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

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

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

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

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

Value

Aggplot2::Geom representing a beeswarm geometry which canbe added to aggplot() object.

Aesthetics

The dots+intervalstats andgeoms have a wide variety of aesthetics that controlthe appearance of their three sub-geometries: thedots (aka theslab), thepoint, and theinterval.

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), thevalue of the data points themselves are used to determine stacking order. Only applies whenlayout is"bin" or"hex", as the other layout methods fully determine bothx andy positions.

• side: Which side to place the slab on."topright","top", and"right" are synonymswhich cause the slab to be drawn on the top or the right depending on iforientation is"horizontal"or"vertical"."bottomleft","bottom", and"left" are synonyms which cause the slabto be drawn on the bottom or the left depending on iforientation 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 bothsides (as in a violin plot).

• scale: What proportion of the region allocated to this geom to use to draw the slab. Ifscale = 1,slabs that use the maximum range will just touch each other. Default is0.9 to leave some spacebetween adjacent slabs. For a comprehensive discussion and examples of slab scaling and normalization,see thethickness scale article.

• justification: Justification of the interval relative to the slab, where0 indicates bottom/leftjustification and1 indicates top/right justification (depending onorientation). IfjustificationisNULL (the default), then it is set automatically based on the value ofside: whenside is"top"/"right"justification is set to0, whenside is"bottom"/"left"justification is set to1, and whenside is"both"justification is set to 0.5.

• datatype: When using composite geoms directly without astat (e.g.geom_slabinterval()),datatype is used toindicate which part of the geom a row in the data targets: rows withdatatype = "slab" target theslab portion of the geometry and rows withdatatype = "interval" target the interval portion ofthe geometry. This is set automatically when using ggdiststats.

Interval-specific aesthetics

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

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

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

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

Point-specific aesthetics

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

Color aesthetics

• colour: (orcolor) The color of theinterval andpoint sub-geometries.Use theslab_color,interval_color, orpoint_color aesthetics (below) toset sub-geometry colors separately.

• fill: The fill color of theslab andpoint sub-geometries. Use theslab_fillorpoint_fill aesthetics (below) to set sub-geometry colors separately.

• alpha: The opacity of theslab,interval, andpoint sub-geometries. Use theslab_alpha,interval_alpha, orpoint_alpha aesthetics (below) to set sub-geometry colors separately.

• colour_ramp: (orcolor_ramp) A secondary scale that modifies thecolorscale to "ramp" to another color. Seescale_colour_ramp() for examples.

• fill_ramp: A secondary scale that modifies thefillscale to "ramp" to another color. Seescale_fill_ramp() for examples.

Line aesthetics

• linewidth: Width of the line used to draw theinterval (except withgeom_slab(): thenit is the width of theslab). With composite geometries including an interval and slab,useslab_linewidth to set the line width of theslab (see below). Forinterval, rawlinewidth values are transformed according to theinterval_size_domain andinterval_size_rangeparameters of thegeom (see above).

• size: Determines the size of thepoint. Iflinewidth is not provided,size willalso determines the width of the line used to draw theinterval (this allows line width andpoint size to be modified together by setting onlysize and notlinewidth). Rawsize values are transformed according to theinterval_size_domain,interval_size_range,andfatten_point parameters of thegeom (see above). Use thepoint_size aesthetic(below) to set sub-geometry size directly without applying the effects ofinterval_size_domain,interval_size_range, andfatten_point.

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

• linetype: Type of line (e.g.,"solid","dashed", etc) used to draw theintervaland the outline of theslab (if it is visible). Use theslab_linetype orinterval_linetype aesthetics (below) to set sub-geometry line types separately.

Slab-specific color and line override aesthetics

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

• slab_colour: (orslab_color) Override forcolour/color: the outline color of the slab.

• slab_alpha: Override foralpha: the opacity of the slab.

• slab_linewidth: Override forlinwidth: the width of the outline of the slab.

• slab_linetype: Override forlinetype: the line type of the outline of the slab.

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