R: Trace plot (time series plot) of MCMC draws

MCMC-traces {bayesplot}

R Documentation

Trace plot (time series plot) of MCMC draws

Description

Trace plot (or 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, np = NULL, np_style = trace_style_np(),
  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)

trace_style_np(div_color = "red", div_size = 0.25, div_alpha = 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)"`). Note: due to partial argument matching `transformations` can be abbreviated for convenience in interactive use (e.g., `transform`, `trans`, etc.).
`facet_args`	A named list of arguments (other than `facets`) passed to `facet_wrap` or `facet_grid` 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 (`mcmc_trace`) or the default point size (`mcmc_trace_highlight`).
`np`	For models fit using `NUTS` (more generally, any symplectic integrator), an optional data frame providing NUTS diagnostic information. The data frame should be the object returned by `nuts_params` or one with the same structure. If `np` is specified then tick marks are added to the bottom of the trace plot indicating within which iterations there was a divergence (if there were any). See the end of the Examples section, below.
`np_style`	A call to the `trace_style_np` helper function to specify arguments controlling the appearance of tick marks representing divergences (if the `np` argument is specified).
`divergences`	Deprecated. Use the `np` argument instead.
`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.
`div_color, div_size, div_alpha`	Optional arguments to the `trace_style_np` helper function that are eventually passed to `geom_rug` if the `np` argument is also specified. They control the color, size, and transparency specifications for showing divergences in the plot. The default values are displayed in the Usage section above.

Value

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

Plot Descriptions

mcmc_trace: Standard trace plots of MCMC draws. For models fit using NUTS, the np argument can be used to also show divergences on the trace plot.
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.

Examples

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

# trace plots of the betas
color_scheme_set("viridis")
mcmc_trace(x, regex_pars = "beta")

color_scheme_set("viridisA")
mcmc_trace(x, regex_pars = "beta")

color_scheme_set("viridisC")
mcmc_trace(x, regex_pars = "beta")


# 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 HMC/NUTS divergences can be displayed in the trace plot
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 trace plot
posterior <- as.array(fit)

# for stanfit and stanreg objects use nuts_params() to get the divergences
mcmc_trace(posterior, pars = "sigma", np = nuts_params(fit))

color_scheme_set("viridis")
mcmc_trace(
  posterior,
  pars = c("wt", "sigma"),
  size = 0.5,
  facet_args = list(nrow = 2),
  np = nuts_params(fit),
  np_style = trace_style_np(div_color = "black", div_size = 0.5)
)

color_scheme_set("viridis")
mcmc_trace(
  posterior,
  pars = c("wt", "sigma"),
  size = 0.8,
  facet_args = list(nrow = 2),
  divergences = nuts_params(fit),
  div_color = "black"
)

## End(Not run)

[Package bayesplot version 1.6.0 Index]