Skip to contents

Identify per-parameter bottlenecks (low ESS/s, low ESS per draw, long time-to-target)

Source: R/assess.R
identify_bottlenecks.Rd

This function ranks parameters according to three metrics:

  • Computational efficiency (CE), defined as ESS per second (low values indicate bottlenecks).

  • Algorithmic efficiency (AE), defined as ESS per post-burnin draw (low values indicate bottlenecks).

  • Time-to-target, defined as the time required to reach a given ESS threshold at the current CE (high values indicate bottlenecks).

Usage

identify_bottlenecks(
  samples,
  runtime_s,
  ess_threshold = 1000,
  sampler_params = NULL,
  model = NULL,
  mcmc_conf = NULL,
  ignore_patterns = c("^lifted_", "^logProb_"),
  strict_sampler_only = TRUE,
  auto_configure = TRUE,
  rhat_threshold = 1.01,
  ess_per_s_min = 0
)

Arguments

samples

An object of class mcmc.list, mcmc, matrix, or data.frame.

runtime_s

Numeric scalar. Total wall-clock time of the MCMC run (in seconds).

ess_threshold

Numeric scalar. Target ESS per parameter used to compute time-to-target. Default is 1000.

sampler_params

Optional character vector of parameter names to retain. If provided, other parameters are ignored.

rhat_threshold

Numeric scalar. Provided for API symmetry but not used in ranking. Default is NULL.

ess_per_s_min

Numeric scalar. Optional threshold for computational efficiency. Parameters with CE below this value are flagged. Set to 0 (default) to disable.

Value

A list with the following elements:

type

Character string. Either "ok" or "degenerate_only".

details

List containing CE, AE, time-to-target, and degenerate sets.

per_param

Data frame with metrics for each parameter.

summary

Data frame summarizing the worst parameters.

top3

Data frame containing the three worst parameters according to CE.

Details

Parameters with non-finite or non-positive ESS, AE, or CE are collected in the degenerate field of the output and excluded from the rankings.

When sampler_params is provided, rankings are restricted to the specified parameter names. This is typically used to exclude deterministic monitors and retain only stochastic nodes that have associated samplers.