Skip to contents

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

Source: R/assess.R
assess_performance_vect.Rd

Compute per-parameter and global performance diagnostics from MCMC output using vectorised implementations of convergence and efficiency metrics. The main outputs are Effective Sample Size (ESS), Gelman–Rubin \(\hat{R}\), Algorithmic Efficiency (AE), and Computational Efficiency (CE).

Usage

assess_performance_vect(
  samples,
  runtime_s,
  rhat_thresh = 1.01,
  ess_type = c("bulk", "tail"),
  drop_const = TRUE,
  tol_var = 0,
  drop_na = TRUE
)

Arguments

samples

MCMC samples: a coda::mcmc.list, coda::mcmc, a matrix/data.frame, or any object accepted by as_mcmc_list().

runtime_s

Numeric scalar; total runtime (seconds) corresponding to the MCMC run(s) that produced samples. This is used to compute CE.

rhat_thresh

Numeric scalar; threshold used to flag lack of convergence based on \(\hat{R}\). Default is 1.01.

ess_type

Character; ESS definition to use. One of "bulk" or "tail" (default = "bulk").

drop_const

Logical; if TRUE, drop parameters with zero or near-zero variance across all chains before computing diagnostics.

tol_var

Numeric scalar; variance tolerance used to identify near-constant parameters (default = 0).

drop_na

Logical; if TRUE, drop rows with missing diagnostics before computing summaries (default = TRUE).

Value

A named list with:

summary

A one-row tibble/data.frame summarising global diagnostics (e.g. median ESS, max \(\hat{R}\), AE/CE summaries).

per_param

A tibble/data.frame with per-parameter ESS, \(\hat{R}\), AE, and CE.

dropped_zero_var

Character vector of parameters removed due to zero or near-zero variance (when drop_const=TRUE).

Details

The function first coerces samples to a coda::mcmc.list (via as_mcmc_list()), then converts it to a posterior draws object to compute diagnostics in a vectorised manner.

Computed metrics:

  • ESS: Effective Sample Size per parameter, computed using posterior::ess_bulk() (bulk ESS) or posterior::ess_tail() (tail ESS), controlled by ess_type.

  • Rhat: Gelman–Rubin convergence diagnostic computed with posterior::rhat() (requires at least two chains).

  • AE: Algorithmic efficiency, defined as ESS / n_draws, where n_draws is the number of retained post-burn-in draws per chain (after thinning).

  • CE: Computational efficiency, defined as ESS / runtime_s.

To improve robustness in high-dimensional models, parameters with zero or near-zero variance across chains can be removed prior to computing ESS and \(\hat{R}\) (drop_const = TRUE). Optionally, rows with missing diagnostics can be removed from summaries (drop_na = TRUE).

See also

effectiveSize, gelman.diag, ess_bulk, ess_tail, rhat

Examples

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