MCMCsummary: Summarize MCMC output

In MCMCvis: Tools to Visualize, Manipulate, and Summarize MCMC Output

Summarize MCMC output

Description

Extract summary information from MCMC output (mean, median, quantiles, Gelman-Rubin convergence statistic, number of effective samples, and specified custom metrics) for specific parameters of interest.

Usage

MCMCsummary(
  object,
  params = "all",
  excl = NULL,
  ISB = TRUE,
  exact = TRUE,
  probs = c(0.025, 0.5, 0.975),
  hpd_prob = 0.95,
  HPD = FALSE,
  pg0 = FALSE,
  digits = NULL,
  round = NULL,
  Rhat = TRUE,
  n.eff = TRUE,
  func = NULL,
  func_name = NULL
)

Arguments

object	Object containing MCMC output. See DETAILS below.
params	Character string (or vector of character strings) denoting parameters to be returned in summary output. Default 'all' returns all parameters in summary output.
excl	Character string (or vector of character strings) denoting parameters to exclude. Used in conjunction with params argument to select parameters of interest.
ISB	Ignore Square Brackets (ISB). Logical specifying whether square brackets should be ignored in the params and excl arguments. If TRUE, square brackets are ignored. If FALSE, square brackets are not ignored. This allows partial names to be used when specifying parameters of interest. Use exact argument to specify whether input from params and excl arguments should be matched exactly.
exact	Logical specifying whether input from params and excl arguments should be matched exactly (after ignoring square brackets if ISB = FALSE). If TRUE, input from params and excl are matched exactly (after taking ISB argument into account). If FALSE, input from params and excl are matched using regular expression format (after taking ISB argument into account).
probs	Numeric vector where each element in (0,1) representing probabilities used to calculate posterior sample quantiles for the selected parameters. Default is c(0.025, 0.5, 0.975).
hpd_prob	Scalar in (0,1) representing probability used to calculate highest posterior density intervals for the selected parameters. Default is 0.95.
HPD	Logical specifying whether to calculate equal-tailed credible intervals (HPD = FALSE) or highest posterior density intervals (HPD = TRUE) for the selected parameters. Default is HPD = FALSE.
pg0	Logical specifying whether to calculate the proportion of the posterior that is greater than 0, rounded to 2 digits.
digits	Number of significant digits to include for posterior summary. All computed digits will be included by default. Note that Rhat is always rounded to 2 decimal places.
round	Number of decimal places to round to for posterior summary. Cannot be used in conjunction with digits argument. Note that Rhat is always rounded to 2 decimal places.
Rhat	Logical specifying whether to calculate and display the potential scale reduction statistic (Rhat). Values near 1 suggest convergence (Brooks and Gelman 1998). Rhat = FALSE will prevent display of this column in summary output. Specifying Rhat = FALSE, may increase function speed for very large mcmc.list objects.
n.eff	Logical specifying whether to calculate and display the number of effective samples for each parameter. n.eff = FALSE will prevent display of this column in summary output. Specifying n.eff = FALSE, may increase function speed for very large mcmc.list objects. Default is n.eff = TRUE.
func	Function to be performed on MCMC output. If a function is specified, it will be evaluated on posteriors for each specified parameter and returned as a column in the summary output (or multiple columns if the function returns more than one value).
func_name	Character string (or vector of character strings) specifying labels for output from func argument. If func_name is not specified, columns with func argument will be labeled 'func'.

Value

Function returns summary information (including parameter posterior mean, posterior sd, quantiles, potential scale reduction statistic (Rhat), number of effective samples, and other specified metrics) for specified parameters.

Details

object argument can be a stanfit object (rstan package), a CmdStanMCMC object (cmdstanr package), a stanreg object (rstanarm package), a brmsfit object (brms package), an mcmc.list object (coda and rjags packages), mcmc object (coda and nimble packages), list object (nimble package), an R2jags model object (R2jags package), a jagsUI model object (jagsUI package), or a matrix containing MCMC chains (each column representing MCMC output for a single parameter, rows representing iterations in the chain). The function automatically detects the object type and proceeds accordingly.

Notes

For mcmc.list, mcmc, and list objects, the potential scale reduction statistic statistic (Rhat) is calculated using the gelman.diag function in the coda package (what is typically displayed in the summary output from models fit with JAGS). For stanfit (as well as CmdStanMCMC, stanreg, and brmsfit objects) and jagsUI objects, Rhat is calculated using a 'split chain' Rhat (in their respective packages), which is thought to be a more conservative diagnostic (Stan Development Team 2018).

For mcmc.list, mcmc, and list objects, the number of effective samples is calculated using the effectiveSize function in the coda package. For stanfit (as well as CmdStanMCMC, stanreg, and brmsfit objects) and jagsUI objects, n.eff is calculated using a slightly different method of computation for the number of effective samples (Stan Development Team 2018). For CmdStanMCMC objects, both bulk and tail n.eff is calculated.

References

Brooks, S. P., and A. Gelman. 1998. General methods for monitoring convergence of iterative simulations. Journal of Computational and Graphical Statistics 7:434.

Stan Development Team. 2018. Stan Modeling Language Users Guide and Reference Manual, Version 2.18.0. https://mc-stan.org

Examples

#Load data
data(MCMC_data)

#Summary information for MCMC output - display 2 significant digits
MCMCsummary(MCMC_data, digits = 2)

#Just 'beta' parameters - round to 2 decimal places
MCMCsummary(MCMC_data, params = 'beta', round = 2)

#Just 'beta[1]', 'beta[4]', and 'alpha[3]'
MCMCsummary(MCMC_data, params = c('beta[1]', 'beta[4]', 'alpha[3]'), ISB = FALSE, exact = TRUE)

MCMCvis documentation built on Oct. 18, 2023, 1:10 a.m.