ggplot2 for RStan

Visual posterior analysis using ggplot2.

stan_plot(object, pars, include = TRUE, unconstrain = FALSE, ...)
  stan_trace(object, pars, include = TRUE, unconstrain = FALSE,
            inc_warmup = FALSE, nrow = NULL, ncol = NULL, ..., 
            window = NULL)
  stan_scat(object, pars, unconstrain = FALSE,
            inc_warmup = FALSE, nrow = NULL, ncol = NULL, ...)
  stan_hist(object, pars, include = TRUE, unconstrain = FALSE,
            inc_warmup = FALSE, nrow = NULL, ncol = NULL, ...)
  stan_dens(object, pars, include = TRUE, unconstrain = FALSE,
            inc_warmup = FALSE, nrow = NULL, ncol = NULL, ..., 
            separate_chains = FALSE)
  stan_ac(object, pars, include = TRUE, unconstrain = FALSE,
            inc_warmup = FALSE, nrow = NULL, ncol = NULL, ..., 
            separate_chains = FALSE, lags = 25, partial = FALSE)
  quietgg(gg)

Arguments

object

A stanfit or stanreg object.

pars

Optional character vector of parameter names. If object is a stanfit object, the default is to show all user-defined parameters or the first 10 (if there are more than 10). If object is a stanreg object, the default is to show all (or the first 10) regression coefficients (including the intercept). For stan_scat only, pars should not be missing and should contain exactly two parameter names.

include

Should the parameters given by the pars argument be included (the default) or excluded from the plot?

unconstrain

Should parameters be plotted on the unconstrained space? Defaults to FALSE. Only available if object is a stanfit object.

inc_warmup

Should warmup iterations be included? Defaults to FALSE.

nrow,ncol

Passed to facet_wrap.

...

Optional additional named arguments passed to geoms (e.g. for stan_trace the geom is geom_path and we could specify linetype, size, alpha, etc.). For stan_plot there are also additional arguments that can be specified in ... (see Details).

window

For stan_trace window is used to control which iterations are shown in the plot. See traceplot.

separate_chains

For stan_dens, should the density for each chain be plotted? The default is FALSE, which means that for each parameter the draws from all chains are combined. For stan_ac, if separate_chains=FALSE (the default), the autocorrelation is averaged over the chains. If TRUE each chain is plotted separately.

lags

For stan_ac, the maximum number of lags to show.

partial

For stan_ac, should partial autocorrelations be plotted instead? Defaults to FALSE.

gg

A ggplot object or an expression that creates one.

Value

A ggplot object that can be further customized using the ggplot2 package.

Note

Because the rstan plotting functions use ggplot2 (and thus the resulting plots behave like ggplot objects), when calling a plotting function within a loop or when assigning a plot to a name (e.g., graph <- plot(fit, plotfun = "rhat")), if you also want the side effect of the plot being displayed you must explicity print it (e.g., (graph <- plot(fit, plotfun = "rhat")), print(graph <- plot(fit, plotfun = "rhat"))).

Details

For stan_plot, there are additional arguments that can be specified in .... The optional arguments and their default values are:

point_est = "median"

The point estimate to show. Either "median" or "mean".

show_density = FALSE

Should kernel density estimates be plotted above the intervals?

ci_level = 0.8

The posterior uncertainty interval to highlight. Central 100*ci_level% intervals are computed from the quantiles of the posterior draws.

outer_level = 0.95

An outer interval to also draw as a line (if show_outer_line is TRUE) but not highlight.

show_outer_line = TRUE

Should the outer_level interval be shown or hidden? Defaults to = TRUE (to plot it).

fill_color, outline_color, est_color

Colors to override the defaults for the highlighted interval, the outer interval (and density outline), and the point estimate.

See also

List of RStan plotting functions, Plot options

Examples

if (FALSE) {
example("read_stan_csv")
stan_plot(fit)
stan_trace(fit)

library(gridExtra)
fit <- stan_demo("eight_schools")

stan_plot(fit)
stan_plot(fit, point_est = "mean", show_density = TRUE, fill_color = "maroon")


# histograms
stan_hist(fit)
# suppress ggplot2 messages about default bindwidth
quietgg(stan_hist(fit))
quietgg(h <- stan_hist(fit, pars = "theta", binwidth = 5)) 

# juxtapose histograms of tau and unconstrained tau 
tau <- stan_hist(fit, pars = "tau")
tau_unc <- stan_hist(fit, pars = "tau", unconstrain = TRUE) + 
            xlab("tau unconstrained")
grid.arrange(tau, tau_unc)

# kernel density estimates
stan_dens(fit)
(dens <- stan_dens(fit, fill = "skyblue", ))
dens <- dens + ggtitle("Kernel Density Estimates\n") + xlab("")
dens

(dens_sep <- stan_dens(fit, separate_chains = TRUE, alpha = 0.3))
dens_sep + scale_fill_manual(values = c("red", "blue", "green", "black"))
(dens_sep_stack <- stan_dens(fit, pars = "theta", alpha = 0.5,
                             separate_chains = TRUE, position = "stack"))

# traceplot
trace <- stan_trace(fit)
trace +
  scale_color_manual(values = c("red", "blue", "green", "black"))
trace +
  scale_color_brewer(type = "div") +
  theme(legend.position = "none")

facet_style <- theme(strip.background = ggplot2::element_rect(fill = "white"),
                     strip.text = ggplot2::element_text(size = 13, color = "black"))
(trace <- trace + facet_style)

# scatterplot
(mu_vs_tau <- stan_scat(fit, pars = c("mu", "tau"), color = "blue", size = 4))
mu_vs_tau + 
  ggplot2::coord_flip() + 
  theme(panel.background = ggplot2::element_rect(fill = "black"))
  
}