bayesplot (version 1.6.0)

MCMC-intervals: Plot interval estimates from MCMC draws

Description

Plot central (quantile-based) posterior interval estimates from MCMC draws. See the Plot Descriptions section, below, for details.

Usage

mcmc_intervals(x, pars = character(), regex_pars = character(),
  transformations = list(), ..., prob = 0.5, prob_outer = 0.9,
  point_est = c("median", "mean", "none"), rhat = numeric())
mcmc_areas(x, pars = character(), regex_pars = character(),
  transformations = list(), ..., prob = 0.5, prob_outer = 1,
  point_est = c("median", "mean", "none"), rhat = numeric(), bw = NULL,
  adjust = NULL, kernel = NULL, n_dens = NULL)
mcmc_areas_ridges(x, pars = character(), regex_pars = character(),
  transformations = list(), ..., prob_outer = 1, prob = 1, bw = NULL,
  adjust = NULL, kernel = NULL, n_dens = NULL)
mcmc_intervals_data(x, pars = character(), regex_pars = character(),
  transformations = list(), ..., prob = 0.5, prob_outer = 0.9,
  point_est = c("median", "mean", "none"), rhat = numeric())
mcmc_areas_data(x, pars = character(), regex_pars = character(),
  transformations = list(), ..., prob = 0.5, prob_outer = 1,
  point_est = c("median", "mean", "none"), rhat = numeric(), bw = NULL,
  adjust = NULL, kernel = NULL, n_dens = NULL)
mcmc_areas_ridges_data(x, pars = character(), regex_pars = character(),
  transformations = list(), ..., prob_outer = 1, prob = 1, bw = NULL,
  adjust = NULL, kernel = NULL, n_dens = NULL)

Arguments

x

A 3-D array, matrix, list of matrices, or data frame of MCMC draws. The MCMC-overview page provides details on how to specify each these allowed inputs.

pars

An optional character vector of parameter names. If neither pars nor regex_pars is specified then the default is to use all parameters.

regex_pars

An optional regular expression to use for parameter selection. Can be specified instead of pars or in addition to pars.

transformations

Optionally, transformations to apply to parameters before plotting. If transformations is a function or a single string naming a function then that function will be used to transform all parameters. To apply transformations to particular parameters, the transformations argument can be a named list with length equal to the number of parameters to be transformed. Currently only univariate transformations of scalar parameters can be specified (multivariate transformations will be implemented in a future release). If transformations is a list, the name of each list element should be a parameter name and the content of each list element should be a function (or any item to match as a function via match.fun, e.g. a string naming a function). If a function is specified by its name as a string (e.g. "log"), then it can be used to construct a new parameter label for the appropriate parameter (e.g. "log(sigma)"). If a function itself is specified (e.g. log or function(x) log(x)) then "t" is used in the new parameter label to indicate that the parameter is transformed (e.g. "t(sigma)").

Note: due to partial argument matching transformations can be abbreviated for convenience in interactive use (e.g., transform, trans, etc.).

...

Currently unused.

prob

The probability mass to include in the inner interval (for mcmc_intervals) or in the shaded region (for mcmc_areas). The default is 0.5 (50% interval) and 1 for mcmc_areas_ridges.

prob_outer

The probability mass to include in the outer interval. The default is 0.9 for mcmc_intervals (90% interval) and 1 for mcmc_areas and for mcmc_areas_ridges.

point_est

The point estimate to show. Either "median" (the default), "mean", or "none".

rhat

An optional numeric vector of \(\hat{R}\) estimates, with one element per parameter included in x. If rhat is provided, the intervals/areas and point estimates in the resulting plot are colored based on \(\hat{R}\) value. See rhat for methods for extracting \(\hat{R}\) estimates.

bw, adjust, kernel, n_dens

Optional arguments passed to density to override default kernel density estimation parameters. n_dens defaults to 1024.

Value

A ggplot object that can be further customized using the ggplot2 package. The _data functions return the data that would have been drawn by the plotting function.

Plot Descriptions

mcmc_intervals

Plots of uncertainty intervals computed from posterior draws with all chains merged.

mcmc_areas

Density plots computed from posterior draws with all chains merged, with uncertainty intervals shown as shaded areas under the curves.

mcmc_areas_ridges

Density plot, as in mcmc_areas, but drawn with overlapping ridgelines. This plot provides a compact display of (hierarchically) related distributions.

See Also

Other MCMC: MCMC-combos, MCMC-diagnostics, MCMC-distributions, MCMC-nuts, MCMC-overview, MCMC-parcoord, MCMC-recover, MCMC-scatterplots, MCMC-traces

Examples

# NOT RUN {
set.seed(9262017)
# some parameter draws to use for demonstration
x <- example_mcmc_draws(params = 6)
dim(x)
dimnames(x)

color_scheme_set("brightblue")
mcmc_intervals(x)
mcmc_intervals(x, pars = c("beta[1]", "beta[2]"))
mcmc_areas(x, regex_pars = "beta\\[[1-3]", prob = 0.8) +
 ggplot2::labs(
   title = "Posterior distributions",
   subtitle = "with medians and 80% intervals"
 )

color_scheme_set("red")
mcmc_areas(
   x,
   pars = c("alpha", "beta[4]"),
   prob = 2/3,
   prob_outer = 0.9,
   point_est = "mean"
)

# color by rhat value
color_scheme_set("blue")
fake_rhat_values <- c(1, 1.07, 1.3, 1.01, 1.15, 1.005)
mcmc_intervals(x, rhat = fake_rhat_values)

mcmc_intervals_data(x)
mcmc_intervals_data(x, rhat = fake_rhat_values)
mcmc_areas_data(x, pars = "alpha")

color_scheme_set("gray")
p <- mcmc_areas(x, pars = c("alpha", "beta[4]"), rhat = c(1, 1.1))
p + legend_move("bottom")
p + legend_move("none") # or p + legend_none()

# }
# NOT RUN {
# apply transformations
mcmc_intervals(
  x,
  pars = c("beta[2]", "sigma"),
  transformations = list("sigma" = "log", "beta[2]" = function(x) x + 3)
)

# apply same transformation to all selected parameters
mcmc_intervals(x, regex_pars = "beta", transformations = "exp")
# }
# NOT RUN {
# }
# NOT RUN {
# example using fitted model from rstanarm package
library(rstanarm)
fit <- stan_glm(
 mpg ~ 0 + wt + factor(cyl),
 data = mtcars,
 iter = 500
)
x <- as.matrix(fit)

color_scheme_set("teal")
mcmc_intervals(x, point_est = "mean", prob = 0.8, prob_outer = 0.95)
mcmc_areas(x, regex_pars = "cyl", bw = "SJ",
           rhat = rhat(fit, regex_pars = "cyl"))
# }
# NOT RUN {
# }
# NOT RUN {
# Example of hierarchically related parameters
# plotted with ridgelines
m <- shinystan::eight_schools@posterior_sample
mcmc_areas_ridges(m, pars = "mu", regex_pars = "theta") +
 ggplot2::ggtitle("Treatment effect on eight schools (Rubin, 1981)")
# }
# NOT RUN {
# }