MCMC Diagnostics

This module provides standard MCMC convergence diagnostics for assessing the quality of posterior samples returned by the Gibbs sampler.

The typical workflow after collecting samples is:

from hydra_tod.mcmc_diagnostics import diagnostics

# samples shape: (n_chains, n_iterations, n_params)
summary = diagnostics(samples, param_names=["logf0", "alpha"])
# summary["logf0"] -> {"ESS_min": ..., "ESS_median": ..., "Rhat_split": ...}

The three key quantities are:

ess_1d()

Effective Sample Size (ESS) — estimates the number of effectively independent samples accounting for autocorrelation. Values well below n_iterations indicate poor mixing.

rhat_split()

Split-:math:`hat{R}` — inter-chain convergence diagnostic. Values close to 1.0 (< 1.01 is a common threshold) indicate that all chains have converged to the same distribution.

acf_1d()

Autocorrelation function (ACF) — FFT-based computation up to a specified maximum lag. Useful for choosing the thinning interval.

diagnostics()

Convenience wrapper that computes ESS and split-\(\hat{R}\) for all parameters and optionally produces trace and ACF plots.