Create MCMC diagnostic plots for nodes of interest

Allows quick visualization of posterior density and trace plots, both separated by chain, for the desired nodes of interest. Includes the ability to plot in the RStudio graphics device, an external device, or a PDF file. Further, with the auto settings, the dimensions of the plotting device scales to the job needed.

diag_plots(
  post,
  params,
  ext_device = FALSE,
  show_diags = "if_poor_Rhat",
  layout = "auto",
  dims = "auto",
  keep_percent = 1,
  save = FALSE,
  file = NULL,
  auto_escape = TRUE
)

Arguments

post	A mcmc.list object.
params	A vector of regular expressions specifying the nodes to match for plotting. Accepts multi-element vectors to match more than one node at a time. See match_params() and vignette("pattern-matching") for more details.
ext_device	Display plots in an external device rather than the active device? FALSE (the default) will plot in the active device (including RStudio window). TRUE will create a new graphics device.
show_diags	Control when to display numerical diagnostic summaries on plots. Must be one of "always", "never", or "if_poor_Rhat". "if_poor_Rhat" (the default) will display the Rhat and effective MCMC samples if the Rhat statistic is greater than 1.1.
layout	Control how parameter diagnostics are organized into "ROWSxCOLUMNS". For example, layout = "4x1" has 4 rows and 1 column of parameter diagnostics. Defaults to "auto", which selects between the only accepted options of "1x1", "2x1", "4x1", "4x2", and "5x3".
dims	Control the dimensions of the graphics device using "HEIGHTxWIDTH" in inches. For example, "5x7" would create a 5 inch tall and 7 inch wide plotting device. Defaults to "auto", which selects the dimensions that look nice when layout = "auto" as well.
keep_percent	Proportion (between 0 and 1) of samples to keep for trace plotting. Passed to post_thin().
save	Save the diagnostic plots in a PDF file? If so, specify file = "example.pdf" as well. Defaults to FALSE.
file	File name of a PDF file to save the plots to. Must include the ".pdf" extension. Saved to working directory by default, but can receive an absolute or relative file path as part of this argument.
auto_escape	Automatically escape "[" and "]" characters for pattern matching? See match_params() for details.

Value

A multi-panel figure showing the posterior density and trace plots for requested nodes. The device in which it is placed depends on the argument values.

Note

If saving as a pdf, these files can get very large with many samples and render slowly. The keep_percent argument is intended to help with this by thinning the chains at quasi-evenly spaced intervals.

See also

match_params(), density_plot(), trace_plot()

Examples

if (interactive()) {
  #load example mcmc.list
  data(cjs)

  # use current device
  diag_plots(cjs, "B0")

  # use a new device
  diag_plots(cjs, "B0", ext_device = TRUE)

  # always show diagnostic summaries
  diag_plots(cjs, "B0", show_diags = "always")

  # use a different layout (leaving it as "auto" is usually best)
  diag_plots(cjs, c("sig", "b"), layout = "5x3")

  # save diagnostics for all nodes to a pdf file
  diag_plots(cjs, "", save = TRUE, file = "diags.pdf")
}