On sample data: stat_[half]eye
Eye plots combine densities (as violins) with intervals to give a more detailed picture of uncertainty than is available just by looking at intervals.
For these first few demos we’ll use these data:
set.seed(1234)
df = tribble(
~group, ~subgroup, ~value,
"a", "h", rnorm(1000, mean = 5),
"b", "h", rnorm(1000, mean = 7, sd = 1.5),
"c", "h", rnorm(1000, mean = 8),
"c", "i", rnorm(1000, mean = 9),
"c", "j", rnorm(1000, mean = 7)
) %>%
unnest(value)
We can summarize it at the group level using an eye plot with stat_eye() (ignoring subgroups for now):
df %>%
ggplot(aes(y = group, x = value)) +
stat_eye() +
ggtitle("stat_eye()")
Users of older versions of tidybayes (which used to contain the ggdist geoms) might have used geom_eye(), which is the older spelling of stat_eye(). Due to the name standardization in version 2 of tidybayes (see the description above), stat_eye() is now the preferred spelling. geom_eye() will continue to work for now, but is deprecated and may throw a warning in future versions.
We can also use stat_halfeye() instead to get densities instead of violins:
df %>%
ggplot(aes(y = group, x = value)) +
stat_halfeye() +
ggtitle("stat_halfeye()")
Or use the side parameter to more finely control where the slab (in this case, the density) is drawn:
p = df %>%
ggplot(aes(x = group, y = value)) +
panel_border()
plot_grid(ncol = 3, align = "hv",
p + stat_eye(side = "left") + labs(title = "stat_eye()", subtitle = "side = 'left'"),
p + stat_eye(side = "both") + labs(subtitle = "side = 'both'"),
p + stat_eye(side = "right") + labs(subtitle = "side = 'right'")
)
Note how the above chart was drawn vertically instead of horizontally: all slabinterval geoms automatically detect their orientation based on the input data. For example, if you use a factor on one axis (say the x axis below), the geom will be drawn along the other axis:
df %>%
ggplot(aes(x = group, y = value)) +
stat_halfeye() +
ggtitle("stat_halfeye()")
If automatic detection of the desired axis fails, you can specify it manually; e.g. with stat_halfeye(orientation = 'vertical') or stat_halfeye(orientation = 'horizontal').
The side parameter works for horizontal geoms as well. "top" and "right" are considered synonyms, as are "bottom" and "left"; either form works with both horizontal and vertical versions of the geoms:
p = df %>%
ggplot(aes(x = value, y = group)) +
panel_border()
plot_grid(ncol = 3, align = "hv",
# side = "left" would give the same result
p + stat_eye(side = "left") + ggtitle("stat_eye()") + labs(subtitle = "side = 'bottom'"),
p + stat_eye(side = "both") + labs(subtitle = "side = 'both'"),
# side = "right" would give the same result
p + stat_eye(side = "right") + labs(subtitle = "side = 'top'")
)
Eye plots are also designed to support dodging through the standard mechanism of position = "dodge". Unlike with geom_violin(), densities in groups that are not dodged (here, ‘a’ and ‘b’) have the same area and max width as those in groups that are dodged (‘c’):
df %>%
ggplot(aes(x = group, y = value, fill = subgroup)) +
stat_eye(position = "dodge") +
ggtitle("stat_eye(position = 'dodge')")
Dodging works whether geoms are horizontal or vertical.
On analytical distributions: stat_dist_[half]eye
The same set of (half-)eye plot stats designed for sample data described above all have corresponding stats for analytical distributions: simply use stat_dist_ instead of stat_ in the name. These stats accept specifications for distributions using the dist and args aesthetics in one of two ways:
Using distribution names as character vectors: this format uses aesthetics as follows:
dist: the name of the distribution, following R’s naming scheme. This is a string which should have "p", "q", and "d" functions defined for it: e.g., “norm” is a valid distribution name because the pnorm(), qnorm(), and dnorm() functions define the CDF, quantile function, and density function of the Normal distribution.args or arg1, … arg9: arguments for the distribution. If you use args, it should be a list column where each element is a list containing arguments for the distribution functions; alternatively, you can pass the arguments directly using arg1, … arg9.
Using distribution vectors from the distributional package: this format uses aesthetics as follows:
dist: a distribution vector produced by functions such as distributional::dist_normal(), distributional::dist_beta(), etc.
For example, here are a variety of normal distributions describing the same data from the previous example:
dist_df = tribble(
~group, ~subgroup, ~mean, ~sd,
"a", "h", 5, 1,
"b", "h", 7, 1.5,
"c", "h", 8, 1,
"c", "i", 9, 1,
"c", "j", 7, 1
)
We can visualize these distributions directly using stat_dist_eye() and the character vector input style to the dist, arg1, and arg2 aesthetics:
dist_df %>%
ggplot(aes(x = group, dist = "norm", arg1 = mean, arg2 = sd, fill = subgroup)) +
stat_dist_eye(position = "dodge") +
ggtitle("stat_dist_eye(position = 'dodge')")
Or we can use the distributional::dist_normal() function to construct a vector of normal distributions. This syntax is often more compact and expressive than the character-vector format above:
dist_df %>%
ggplot(aes(x = group, dist = dist_normal(mean, sd), fill = subgroup)) +
stat_dist_eye(position = "dodge") +
ggtitle("stat_dist_eye(position = 'dodge')")
This makes it easy to visualize a variety of distributions. E.g., here are some Beta distributions:
data.frame(alpha = seq(5, 100, length.out = 10)) %>%
ggplot(aes(y = alpha, dist = dist_beta(alpha, 10))) +
stat_dist_halfeye() +
labs(
title = "stat_dist_halfeye()",
x = "Beta(alpha,10) distribution"
)
If you want to plot all of these on top of each other (instead of stacked), you could turn off plotting of the interval to make the plot easier to read using stat_dist_halfeye(show_interval = FALSE, ...). A shortcut for stat_dist_halfeye(show_interval = FALSE, ...) is stat_dist_slab(). We’ll also turn off the fill color with fill = NA to make the stacking easier to see, and use outline color to show the value of alpha:
data.frame(alpha = seq(5, 100, length.out = 10)) %>%
ggplot(aes(y = "", dist = dist_beta(alpha, 10), color = alpha)) +
stat_dist_slab(fill = NA) +
coord_cartesian(expand = FALSE) +
scale_color_viridis_c() +
labs(
title = "stat_dist_slab(fill = NA)",
x = "Beta(alpha,10) distribution",
y = NULL
)
The approach of using arg1, … arg9 can work well when comparing similar distributions, but is harder to use with different distribution types. For example, if we wished to compare a Student t distribution and Normal distribution, the arguments may not line up. This is a good case to use list columns and the args aesthetic. ggdist includes an implementation of the scaled and shifted Student t distribution (dstudent_t(), pstudent_t(), etc) as it is often needed for visualizing frequentist confidence distributions (see vignette("freq-uncertainty-vis")) and Bayesian priors:
tribble(
~ dist, ~ args,
"norm", list(0, 1),
"student_t", list(3, 0, 1)
) %>%
ggplot(aes(y = dist, dist = dist, args = args)) +
stat_dist_halfeye() +
ggtitle("stat_dist_halfeye()")
A particularly good use of the dist stats is to visualize priors. For example, with brms you can specify priors using the brms::prior() function, which creates data frames with a "prior" column indicating the name of the prior distribution as a string. E.g., I might set some priors on the betas and the standard deviation in a model with something like this:
# NB these priors are made up!
priors = c(
prior(normal(0,1), class = b),
prior(lognormal(0,1), class = sigma)
)
priors
| normal(0, 1) |
b |
|
|
|
|
|
|
| lognormal(0, 1) |
sigma |
|
|
|
|
|
|
The parse_dist function can make it easier to visualize these: it takes in string specifications like those produced by brms — "normal(0,1)" and "lognormal(0,1)" above — and translates them into .dist and .args columns:
priors %>%
parse_dist(prior)
| normal(0, 1) |
b |
|
|
|
|
|
|
norm |
0, 1 |
| lognormal(0, 1) |
sigma |
|
|
|
|
|
|
lnorm |
0, 1 |
Notice that it also automatically translate some common distribution names (e.g. “normal” and “lognormal”) into their equivalent R function names ("norm" and "lnorm"). This makes it easy to use them with stat_dist_eye() and its variants:
priors %>%
parse_dist(prior) %>%
ggplot(aes(y = class, dist = .dist, args = .args)) +
stat_dist_halfeye() +
labs(
title = "stat_dist_halfeye()",
subtitle = "with brms::prior() and ggdist::parse_dist() to visualize priors",
x = NULL
)
The stat_dist_... family also adjusts densities appropriately when scale transformations are applied. For example, here is a log-Normal distribution plotted on a log scale:
data.frame(dist = "lnorm") %>%
ggplot(aes(y = 0, dist = dist, arg1 = log(10), arg2 = 2*log(10))) +
stat_dist_halfeye() +
scale_x_log10(breaks = 10^seq(-5,7, by = 2))
As expected, a log-Normal density plotted on the log scale appears Normal. The Jacobian for the scale transformation is applied to the density so that the correct density is shown on the log scale. Internally, numerical differentiation is used to calculate the Jacobian so that the stat_dist_... family works generically across the different scale transformations supported by ggplot.
