MCMCtraces.Rd
Trace plot (or traceplot) of MCMC draws. See the Plot Descriptions section, below, for details.
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(), ..., 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_trace_data(x, pars = character(), regex_pars = character(), transformations = list(), ..., highlight = NULL, n_warmup = 0, iter1 = 0)
x  A 3D array, matrix, list of matrices, or data frame of MCMC draws.
The MCMCoverview page provides details on how to specify each these
allowed inputs. It is also possible to use an object with an


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 
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.
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.
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.
Other MCMC: MCMCcombos
,
MCMCdiagnostics
,
MCMCdistributions
,
MCMCintervals
, MCMCnuts
,
MCMCoverview
, MCMCparcoord
,
MCMCrecover
,
MCMCscatterplots
# some parameter draws to use for demonstration x < example_mcmc_draws(chains = 4, params = 6) dim(x)#> [1] 250 4 6dimnames(x)#> $Iteration #> NULL #> #> $Chain #> [1] "chain:1" "chain:2" "chain:3" "chain:4" #> #> $Parameter #> [1] "alpha" "sigma" "beta[1]" "beta[2]" "beta[3]" "beta[4]" #># 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_overlay(x, "alpha")# 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)#> Warning: There were 23 divergent transitions after warmup. Increasing adapt_delta above 0.8 may help. See #> http://mcstan.org/misc/warnings.html#divergenttransitionsafterwarmup#> Warning: Examine the pairs() plot to diagnose sampling problems#> Warning: Bulk Effective Samples Size (ESS) is too low, indicating posterior means and medians may be unreliable. #> Running the chains for more iterations may help. See #> http://mcstan.org/misc/warnings.html#bulkess#> Warning: Tail Effective Samples Size (ESS) is too low, indicatingposterior variances and tail quantiles may be unreliable. #> Running the chains for more iterations may help. See #> http://mcstan.org/misc/warnings.html#tailess# 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) )mcmc_trace( posterior, pars = c("wt", "sigma"), size = 0.8, facet_args = list(nrow = 2), divergences = nuts_params(fit), div_color = "black" )#> Warning: The 'divergences' argument is deprecated and will be removed in a future release. Use the 'np' argument instead.#> Warning: The following arguments were unrecognized and ignored: div_color