Plots: ggplot2 for RStan

Description

Visual posterior analysis using ggplot2.

Usage

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)

Value

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

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.

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.

Examples

Run this code

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"))
  
}