Skip to contents

Assess MCMC performance metrics (ESS, R-hat, AE, CE)

Source: R/assess.R
assess_performance.Rd

Compute per-parameter and global diagnostics from an MCMC sample set. Metrics include Effective Sample Size (ESS), Gelman-Rubin R-hat, Algorithmic Efficiency (AE = ESS / total draws), and Computational Efficiency (CE = ESS / runtime in seconds).

Usage

assess_performance(samples, runtime_s, rhat_thresh = 1.01)

Arguments

samples

A list of MCMC samples or any object that can be converted by as_mcmc_list().

runtime_s

Numeric scalar. Total runtime of the MCMC run (seconds).

rhat_thresh

Numeric scalar. Threshold used to flag R-hat values indicating lack of convergence. Default is 1.01.

Value

A named list containing:

summary

A one-row tibble summarizing global diagnostics.

per_param

A tibble containing ESS, Rhat, AE, and CE for each parameter.

Details

The function first coerces the input to an mcmc.list object and then computes the following:

  • ESS: Effective Sample Size for each parameter.

  • Rhat: Gelman-Rubin diagnostic (computed only when two or more chains are available).

  • AE: Algorithmic efficiency, defined as ESS divided by the total number of retained post-burnin draws.

  • CE: Computational efficiency, defined as ESS divided by the total runtime in seconds.

When the posterior package is installed, its implementation of rhat() is used; otherwise, diagnostics from coda are applied.

See also

coda::effectiveSize, coda::gelman.diag, posterior::rhat

Examples

if (FALSE) { # \dontrun{
res <- run_baseline_config(build_M, niter = 2000, nburnin = 500, thin = 2)
perf <- assess_performance(res$samples, runtime_s = res$runtime_s)
perf$summary
} # }