In mjskay/ggdist: Visualizations of Distributions and Uncertainty

knitr::opts_chunk$set(
  fig.path = "man/figures/README/"
)
knitr::opts_chunk$set(
  fig.retina = 2
)
if (requireNamespace("ragg", quietly = TRUE)) {
  knitr::opts_chunk$set(
    dev = "ragg_png"
  )
} else if (capabilities("cairo")) {
  knitr::opts_chunk$set(
    dev = "png",
    dev.args = list(png = list(type = "cairo"))
  )
}

ggdist: Visualizations of distributions and uncertainty

library(dplyr)
library(tidyr)
library(distributional)
library(ggdist)
library(ggplot2)
library(patchwork)

theme_set(theme_ggdist())

set.seed(12345)
d = dist_normal(4, 1)
d_quantiles = dist_sample(list(qnorm(ppoints(1000), 4, 1)))
q_100 = qnorm(ppoints(100), 4, 1)
x_samples_100 = rnorm(100, 4, 1)
d_samples_100 = dist_sample(list(x_samples_100))

dists_xlim = c(0,8)

slabinterval_plot = ggplot() +
  stat_halfeye(aes(y = "01", xdist = d)) +
  stat_eye(aes(y = "02", xdist = d)) +
  stat_gradientinterval(aes(y = "03", xdist = d), scale = 0.75, fill_type = "gradient", show_interval = FALSE, show_point = FALSE, position = position_nudge(y = -0.2)) +
  stat_ccdfinterval(aes(y = "04", xdist = d), scale = .5, justification = 0, position = position_nudge(y = -0.3)) +
  stat_cdfinterval(aes(y = "05", xdist = d), scale = .5, justification = 0, position = position_nudge(y = -0.2)) +
  stat_interval(
    aes(y = "06", xdist = d), color = "gray65", alpha = 1/3, linewidth = 10,
    position = position_nudge(y = -.1)
  ) +
  stat_pointinterval(aes(y = "07", xdist = d)) +
  stat_slab(aes(y = "08", xdist = d), position = position_nudge(y = - 0.2)) +
  stat_histinterval(aes(y = "09", xdist = d_quantiles), position = position_nudge(y = - 0.25)) +
  stat_slab(
    aes(y = "10", xdist = d, fill_ramp = after_stat(level)), 
    show.legend = FALSE, .width = c(.5, .8, .95),
    fill = scales::brewer_pal()(7)[[5]],
    position = position_nudge(y = -0.5)    
  ) +
  stat_spike(
    aes(y = "10", xdist = d, linetype = after_stat(at)),
    at = c(mode = Mode, qi = function(...) qi(..., .width = .8)),
    show.legend = FALSE,
    position = position_nudge(y = -0.5)
  ) +
  scale_x_continuous(limits = dists_xlim, expand = c(0,0), labels = NULL) +
  scale_y_discrete(limits = rev, labels = NULL) +
  labs(
    title = "slabinterval",
    x = NULL,
    y = NULL
  ) +
  theme(plot.margin = margin(5.5, 5.5, 5.5, 0), axis.ticks = element_blank())

set.seed(123456)
x1 = rnorm(125, 3, 0.75)
x2 = rnorm(125, 5, 0.75)

dotsinterval_plot = ggplot() +
  stat_dotsinterval(aes(y = "01", xdist = d)) +
  stat_dots(aes(y = "02", xdist = d), layout = "weave", position = position_nudge(y = -0.2)) +
  geom_weave(aes(y = "03", x = x1, fill = x1 > 4, group = NA), linewidth = NA, alpha = 0.75, binwidth = NA) +
  geom_swarm(aes(y = "04", x = x2, fill = x2 > 4, group = NA), linewidth = NA, alpha = 0.75, binwidth = NA, position = position_nudge(y = 0.1)) +
  scale_fill_brewer(palette = "Dark2", guide = "none") +

  ggnewscale::new_scale_fill() +
  stat_dotsinterval(aes(y = "05", xdist = d, fill = after_stat(level)), layout = "weave", slab_linewidth = NA, .width = c(.66, .95), quantiles = 200, position = position_nudge(y = -0.3)) +
  scale_color_manual(values = scales::brewer_pal()(3)[-1], aesthetics = "fill", guide = "none") +

  ggnewscale::new_scale_fill() +
  geom_dots(aes(y = "06", x = x1, fill = "a"), side = "bottom", scale = 0.75, linewidth = NA, position = position_nudge(y = -0.1)) +
  stat_slabinterval(aes(y = "06", x = x1, fill = "a"), scale = 0.5, position = position_nudge(y = -0.1)) +
  geom_dots(aes(y = "07", x = x2, fill = "b"), side = "bottom", scale = 0.75, linewidth = NA, position = position_nudge(y = -0.2)) +
  stat_slabinterval(aes(y = "07", x = x2, fill = "b"), scale = 0.5, position = position_nudge(y = -0.2)) +
  scale_fill_brewer(palette = "Set2", guide = "none") +


  scale_x_continuous(limits = dists_xlim, expand = c(0,0), labels = NULL) +
  scale_y_discrete(limits = rev, labels = NULL) +
  labs(
    title = "dotsinterval",
    x = NULL,
    y = NULL
  ) +
  theme(axis.ticks = element_blank())

m_mpg = lm(mpg ~ hp * cyl, data = mtcars)
mtcars_preds = mtcars %>%
  group_by(cyl) %>%
  expand(hp = seq(min(hp), max(hp), length.out = 50)) %>%
  bind_cols(predict(m_mpg, newdata = ., se.fit = TRUE))

mtcars_plot = function(.width = c(.5, .8, .95), alpha = 1/4, ...) {
  mtcars_preds %>%
    ggplot(aes(x = hp, fill = ordered(cyl), color = ordered(cyl))) +
    stat_lineribbon(
      aes(ydist = dist_student_t(df, fit, se.fit)), 
      .width = .width, alpha = alpha, ...
    ) +
    geom_point(aes(y = mpg), data = mtcars) +

    scale_fill_brewer(palette = "Set2") +
    scale_color_brewer(palette = "Dark2") +
    labs(
      color = "cyl",
      fill = "cyl",
      y = "mpg"
    ) +
    theme_ggdist()
}

lineribbon_plot_1 = mtcars_plot() +
  guides(color = "none", fill = "none", x = "none") +
  scale_x_continuous(labels = NULL) +
  scale_y_continuous(labels = NULL) +
  labs(title = "lineribbon", x = NULL, y = NULL) +
  theme(plot.margin = margin(5.5, 5.5, 0, 5.5), axis.ticks = element_blank())
lineribbon_plot_2 = mtcars_plot(.width = ppoints(30), alpha = 1/20) +
  guides(color = "none", fill = "none") +
  scale_x_continuous(labels = NULL) +
  scale_y_continuous(labels = NULL) +
  labs(x = NULL, y = NULL) +
  theme(plot.margin = margin(0, 5.5, 5.5, 5.5), axis.ticks = element_blank())

slabinterval_plot + dotsinterval_plot + (lineribbon_plot_1 / lineribbon_plot_2) +
  plot_annotation(
    caption = 'Some examples from the three main families of ggdist geometries'
  )

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

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

The geom_dotsinterval() / stat_dotsinterval() family (see vignette("dotsinterval")) makes it easy to visualize dot+interval plots, Wilkinson dotplots, beeswarm plots, and quantile dotplots (and combined with half-eyes, composite plots like rain cloud plots):

set.seed(12345) # for reproducibility

data.frame(
  abc = c("a", "b", "c"),
  value = rnorm(300, c(1, 8, 3), c(1, 1.7, 1))
) %>%
  ggplot(aes(y = abc, x = value, fill = abc)) +
  stat_slab() +
  stat_dotsinterval(side = "bottom", slab_linewidth = NA) +
  scale_fill_brewer(palette = "Set2") +
  theme_ggdist()

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

mtcars_plot()

All stats in {ggdist} also support visualizing analytical distributions and vectorized distribution data types like distributional objects or posterior::rvar() objects. This is particularly useful when visualizing uncertainty in frequentist models (see vignette("freq-uncertainty-vis")) or when visualizing priors in a Bayesian analysis.

The {ggdist} geoms and stats also form a core part of the tidybayes package (in fact, they originally were part of {tidybayes}). For examples of the use of {ggdist} geoms and stats for visualizing uncertainty in Bayesian models, see the vignettes in {tidybayes}, such as vignette("tidybayes", package = "tidybayes") or vignette("tidy-brms", package = "tidybayes").

Cheat sheets

These cheat sheets focus on the slabinterval family of geometries:

Installation

You can install the currently-released version from CRAN with this R command:

install.packages("ggdist")

Alternatively, you can install the latest development version from GitHub with these R commands:

install.packages("devtools")
devtools::install_github("mjskay/ggdist")

Dependencies

{ggdist} aims to have minimal additional dependencies beyond those already required by {ggplot2}. The {ggdist} dependencies fall into the following categories:

1. {ggplot2}.

2. Packages that {ggplot2} also depends on. These packages add no additional dependency cost because {ggplot2} already requires them: {rlang}, {cli}, {scales}, {tibble}, {vctrs}, {withr}, {gtable}, and {glue}.

3. Packages that {ggplot2} does not depend on. These are all well-maintained packages with few dependencies and a clear need within {ggdist}:

4. {distributional}: this implementation of distribution vectors powers much of {ggdist}. This package adds minimal additional cost, as its only dependency that is not also a dependency of {ggplot2} is {numDeriv}, which is needed by {ggdist} anyway (see below).
5. {numDeriv}: used for calculating Jacobians of scale transformations. Needed because testing has revealed common situations where stats::numericDeriv() fails but {numDeriv} does not. Widely used by other CRAN packages and has no additional dependencies.
6. {quadprog}: Used to solve constrained optimization problems during different parts of dotplot layout, particularly to avoid dot overlaps in the "bin" and "weave" layouts. Widely used by other CRAN packages and has no additional dependencies.
7. {Rcpp}: Used to implement faster dotplot layout. Widely used by other CRAN packages and has no additional dependencies.

Feedback, issues, and contributions

I welcome feedback, suggestions, issues, and contributions! If you have found a bug, please file it here with minimal code to reproduce the issue. Pull requests should be filed against the dev branch. I am not particularly reliable over email, though you can try to contact me at [e-mail]. A Twitter DM is more likely to elicit a response.

Citing ggdist

Matthew Kay (2024). ggdist: Visualizations of Distributions and Uncertainty in the Grammar of Graphics. IEEE Transactions on Visualization and Computer Graphics, 30(1), 414--424. DOI: 10.1109/TVCG.2023.3327195.

Matthew Kay (r format(Sys.Date(), "%Y")). ggdist: Visualizations of Distributions and Uncertainty. R package version r getNamespaceVersion("ggdist"), https://mjskay.github.io/ggdist/. DOI: 10.5281/zenodo.3879620.

mjskay/ggdist documentation built on Nov. 21, 2024, 10:46 a.m.