MCMCtraces {bayesplot}  R Documentation 
Trace and rank plots of MCMC draws
Description
Trace and rank plots 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,
iter1 = 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)
mcmc_rank_overlay(
x,
pars = character(),
regex_pars = character(),
transformations = list(),
facet_args = list(),
...,
n_bins = 20,
ref_line = FALSE
)
mcmc_rank_hist(
x,
pars = character(),
regex_pars = character(),
transformations = list(),
...,
facet_args = list(),
n_bins = 20,
ref_line = FALSE
)
mcmc_rank_ecdf(
x,
pars = character(),
regex_pars = character(),
transformations = list(),
...,
K = NULL,
facet_args = list(),
prob = 0.99,
plot_diff = FALSE,
interpolate_adj = NULL
)
mcmc_trace_data(
x,
pars = character(),
regex_pars = character(),
transformations = list(),
...,
highlight = NULL,
n_warmup = 0,
iter1 = 0
)
Arguments
x 
An object containing MCMC draws:

pars 
An optional character vector of parameter names. If neither

regex_pars 
An optional regular expression to use for
parameter selection. Can be specified instead of 
transformations 
Optionally, transformations to apply to parameters
before plotting. If Note: due to partial argument matching 
... 
Currently ignored. 
facet_args 
A named list of arguments (other than 
n_warmup 
An integer; the number of warmup iterations included in

iter1 
An integer; the iteration number of the first included draw
(default is 
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
for 
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 
np_style 
A call to the 
divergences 
Deprecated. Use the 
alpha 
For 
highlight 
For 
div_color , div_size , div_alpha 
Optional arguments to the

n_bins 
For the rank plots, the number of bins to use for the histogram
of ranknormalized MCMC samples. Defaults to 
ref_line 
For the rank plots, whether to draw a horizontal line at the
average number of ranks per bin. Defaults to 
K 
An optional integer defining the number of equally spaced evaluation
points for the PITECDF. Reducing K when using 
prob 
For 
plot_diff 
For 
interpolate_adj 
A boolean defining if the simultaneous confidence
bands should be interpolated based on precomputed values rather than
computed exactly. Computing the bands may be computationally intensive and
the approximation gives a fast method for assessing the ECDF trajectory.
The default is to use interpolation if 
Value
The plotting functions return a ggplot object that can be further
customized using the ggplot2 package. The functions with suffix
_data()
return the data that would have been drawn by the plotting
function.
mcmc_trace_data()
returns the data for the trace and rank plots
in the same data frame.
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. mcmc_rank_hist()

Whereas traditional trace plots visualize how the chains mix over the course of sampling, rank histograms visualize how the values from the chains mix together in terms of ranking. An ideal plot would show the rankings mixing or overlapping in a uniform distribution. See Vehtari et al. (2019) for details.
mcmc_rank_overlay()

Ranks from
mcmc_rank_hist()
are plotted using overlaid lines in a single panel. mcmc_rank_ecdf()

The ECDFs of the ranks from
mcmc_rank_hist()
are plotted with the simultaneous confidence bands with a coverage determined byprob
, that is, bands that completely cover all of the rank ECDFs with the probabilityprob
. Ifplot_diff = TRUE
, the difference between the observed rank ECDFs and the theoretical expectation for samples originating from the same distribution is drawn. See Säilynoja et al. (2021) for details.
References
Vehtari, A., Gelman, A., Simpson, D., Carpenter, B., Bürkner, P. (2019). Ranknormalization, folding, and localization: An improved Rhat for assessing convergence of MCMC. arXiv preprint.
Säilynoja, T., Bürkner, P., Vehtari, A. (2021). Graphical Test for Discrete Uniformity and its Applications in Goodness of Fit Evaluation and Multiple Sample Comparison arXiv preprint.
See Also
Other MCMC:
MCMCcombos
,
MCMCdiagnostics
,
MCMCdistributions
,
MCMCintervals
,
MCMCnuts
,
MCMCoverview
,
MCMCparcoord
,
MCMCrecover
,
MCMCscatterplots
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("mixbluered")
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")
# Ranknormalized histogram plots. Instead of showing how chains mix over
# time, look at how the ranking of MCMC samples mixed between chains.
color_scheme_set("viridisE")
mcmc_rank_hist(x, "alpha")
mcmc_rank_hist(x, pars = c("alpha", "sigma"), ref_line = TRUE)
mcmc_rank_overlay(x, "alpha")
# ECDF and ECDF difference plots of the ranking of MCMC samples between chains.
# Provide 99% simultaneous confidence intervals for the chains sampling from
# the same distribution.
mcmc_rank_ecdf(x, prob = 0.99)
mcmc_rank_ecdf(x, prob = 0.99, plot_diff = TRUE)
## 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, refresh = 0,
# 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)
)
## End(Not run)