postpack (version 0.5.4)

diag_plots: Create MCMC diagnostic plots for nodes of interest

Description

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.

Usage

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
)

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.

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.

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