plot.mcmc_dm: Plot MCMC Results and Diagnostics for `mcmc_dm` Objects

Description

Visualize MCMC results and diagnostics for mcmc_dm objects. The function plot.mcmc() is typically called when users supply an mcmc_dm object returned by estimate_dm() to the generic base::plot() function.

Usage

# S3 method for mcmc_dm
plot(x, ..., id = NULL, what = "trace", bundle_plots = TRUE)

Value

Returns NULL invisibly.

Arguments

x: an object of class mcmc_dm, as returned by estimate_dm().
...: optional arguments passed on to the underlying plotting functions plot_mcmc_trace(), plot_mcmc_marginal(), and plot_mcmc_auto(). See the respective documentations for a list of optional arguments and the examples below. Probably the most relevant optional argument is which_prms that allows users to select a specific subset of parameters.
id: optional character vector, specifying the id(s) of participants to plot. If length(id) > 1, plot.mcmc_dm() is called recursively, iterating over each entry in id. Each id must match with the relevant dimension names of the used chains array stored in x.
what: a character string indicating the type of plot to produce. Must be either "trace", "density", or "auto". See the Details below. Default is "trace".
bundle_plots: logical, indicating whether to display separate panels in a single plot layout (FALSE), or to plot them separately (TRUE).

Details

This function provides diagnostic and summary visualizations of MCMC samples. It handles results from both hierarchical and non-hierarchical MCMC runs:

If id is provided, the plot refers to the requested participant, with MCMC results extracted at the individual level.
If id is omitted, plots refer to group-level parameters (i.e., the hyperparameters)

The following plot types are supported:

Trace plots (what = "trace"): These plots show sampled parameter values across MCMC iterations for each chain. They are primarily used to inspect convergence and mixing behavior. Ideally, all chains should appear well-mixed (i.e., they should overlap and sample in a similar range). Lack of convergence is indicated by chains that remain in separate regions or exhibit trends over time.
Density plots (what = "density"): These plots display smoothed marginal posterior distributions for each parameter, collapsed over chains and iterations. They are useful for understanding the central tendency, variance, and shape of the posterior distributions.
Autocorrelation plots (what = "auto"): These plots display the autocorrelation at different lags, averaged across chains. They are useful to judge how quickly the chains produced independent samples.

Examples

Run this code

# get an examplary `mcmc_dm` object
chains_obj <- get_example_fits("mcmc")
plot(chains_obj)
plot(chains_obj, what = "density")
plot(chains_obj, what = "density", which_prm = "b", bundle_plots = FALSE)