bayesplot (version 1.2.0)

MCMC-traces: Traceplot (time series plot) of MCMC draws

Description

Traceplot of MCMC draws. See the Plot Descriptions section, below, for details.

Usage

mcmc_trace(x, pars = character(), regex_pars = character(),
  transformations = list(), facet_args = list(), ..., n_warmup = 0,
  window = NULL, size = NULL, divergences = NULL)
mcmc_trace_highlight(x, pars = character(), regex_pars = character(),
  transformations = list(), facet_args = list(), ..., n_warmup = 0,
  window = NULL, size = NULL, alpha = 0.2, highlight = 1)

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

facet_args

Arguments (other than facets) passed to facet_wrap to control faceting.

...

Currently ignored.

n_warmup

An integer; the number of warmup iterations included in x. The default is n_warmup = 0, i.e. to assume no warmup iterations are included. If n_warmup > 0 then the background for iterations 1:n_warmup is shaded gray.

window

An integer vector of length two specifying the limits of a range of iterations to display.

size

An optional value to override the default line size (if calling mcmc_trace) or the default point size (if calling mcmc_trace_highlight).

divergences

For models fit using NUTS (more generally, any symplectic integrator), an optional vector or data frame providing information about divergent transitions. If a data frame is provided it should be an object returned by nuts_params (or an object with the same structure). If a vector is provided it should be a vector with one element per iteration, with each element either 0 (no divergence) or 1 (a divergence in at least one chain). If divergences is specified then red tick marks are added to the bottom of the traceplot indicating within which iterations there was a divergence. See the end of the Examples section, below.

alpha

For mcmc_trace_highlight, passed to geom_point to control the transparency of the points for the chains not highlighted.

highlight

For mcmc_trace_highlight, an integer specifying one of the chains that will be more visible than the others in the plot.

Value

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

Plot Descriptions

mcmc_trace

Standard traceplots of MCMC draws. For models fit using NUTS the divergences argument can be used to also show divergences on the traceplot.

mcmc_trace_highlight

Traces are plotted using points rather than lines and the opacity of all chains but one (specified by the highlight argument) is reduced.

See Also

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

Examples

# NOT RUN {
# some parameter draws to use for demonstration
x <- example_mcmc_draws(chains = 4, params = 6)
dim(x)
dimnames(x)

# traceplots of the betas
color_scheme_set("viridis")
mcmc_trace(x, regex_pars = "beta")
# }
# NOT RUN {
color_scheme_set("viridisA")
mcmc_trace(x, regex_pars = "beta")

color_scheme_set("viridisC")
mcmc_trace(x, regex_pars = "beta")
# }
# NOT RUN {
# mix color schemes
color_scheme_set("mix-blue-red")
mcmc_trace(x, regex_pars = "beta")

# use traditional ggplot discrete color scale
mcmc_trace(x, pars = c("alpha", "sigma")) +
 ggplot2::scale_color_discrete()

# zoom in on a window of iterations, increase line size,
# add tick marks, move legend to the top, add gray background
color_scheme_set("viridisA")
mcmc_trace(x[,, 1:4], window = c(100, 130), size = 1) +
  panel_bg(fill = "gray90", color = NA) +
  legend_move("top")

# }
# NOT RUN {
# parse facet label text
color_scheme_set("purple")
p <- mcmc_trace(
  x,
  regex_pars = "beta\\[[1,3]\\]",
  facet_args = list(labeller = ggplot2::label_parsed)
)
p + facet_text(size = 15)

# mark first 100 draws as warmup
mcmc_trace(x, n_warmup = 100)

# plot as points, highlighting chain 2
color_scheme_set("brightblue")
mcmc_trace_highlight(x, pars = "sigma", highlight = 2, size = 2)

# for models fit using NUTS divergences can be displayed in the traceplot
library("rstanarm")
fit <- stan_glm(mpg ~ ., data = mtcars,
  # next line to keep example fast and also ensure we get some divergences
                prior = hs(), iter = 400, adapt_delta = 0.8)

# extract draws using as.array (instead of as.matrix) to keep
# chains separate for traceplot
posterior <- as.array(fit)

# for stanfit and stanreg objects use nuts_params() to get the divergences
mcmc_trace(
  posterior,
  pars = "sigma",
  divergences = nuts_params(fit) # or nuts_params(fit, pars = "divergent__")
)
# }
# NOT RUN {
# }