mixle.inference.diagnostics module¶
Public MCMC convergence diagnostics over plain arrays.
These functions are deliberately free of any MCMCResult / _Slot dependency: they
operate on ordinary NumPy arrays so the draws of any sampler (mixle’s or an external one)
can be diagnosed. They are the generic cores behind mixle.inference.mcmc.gelman_rubin and
MCMCResult.effective_sample_size.
- rhat(chains)[source]
Gelman-Rubin potential scale reduction factor (R-hat) per parameter dimension.
R-hat compares the variance between chains to the variance within chains. Values near 1.0 indicate the chains have mixed and are sampling a common target; values above ~1.01-1.1 flag non-convergence. Standard multi-chain check (Gelman & Rubin 1992).
- ess(samples, max_lag=None)[source]
Effective sample size per parameter from positive autocorrelation lags.
Accepts a single chain
(n_draws,)/(n_draws, d)or a stack of chains(n_chains, n_draws, d)(the chains are pooled into one autocorrelation estimate after centering each chain by its own mean). Uses the initial-positive-sequence truncation (Geyer): sum autocorrelations until the first non-positive lag.
- split_rhat(chains)[source]
Rank-normalized split-R-hat (Vehtari et al. 2021) – the robust, recommended R-hat.
Splits each chain in half (doubling the chain count, so within-chain non-stationarity is caught), rank-normalizes the pooled draws (robust to heavy tails / non-normality), then applies the Gelman-Rubin R-hat. Convergence is typically declared at
< 1.01.
- ess_bulk(chains)[source]
Bulk effective sample size: ESS of the rank-normalized split chains (mixing in the distribution body).
- ess_tail(chains, prob=0.05)[source]
Tail effective sample size: the smaller ESS of the lower-/upper-
probtail indicators.Tail quantiles mix more slowly than the bulk; tail-ESS is
min(ESS[1(x <= q_prob)], ESS[1(x >= q_{1-prob})])over the split chains (Vehtari et al. 2021), surfacing poor tail exploration that bulk-ESS misses.
- folded_split_rhat(chains)[source]
Folded rank-normalized split-R-hat (Vehtari et al. 2021): split-R-hat on
|x - median(x)|.The plain
split_rhat()compares chain locations; folding about the median makes it compare chain scales/tails, catching the case where chains share a mean but differ in spread. Use together withsplit_rhat()(orrhat_max()).
- rhat_max(chains)[source]
The recommended convergence R-hat:
max(split_rhat, folded_split_rhat)(Vehtari et al. 2021).A single number that flags non-convergence in either the location (bulk) or the scale (folded) of the chains; declare convergence at
< 1.01.
- mcse_mean(chains)[source]
Monte Carlo standard error of the posterior mean:
sd(x) / sqrt(ESS)per parameter.The sampling error in the estimated mean from autocorrelated draws – the posterior standard deviation deflated by the (autocorrelation-based) effective sample size of the raw chains.
- mcmc_summary(chains)[source]
Per-parameter posterior + convergence summary (the ArviZ-style
summarytable).Returns one dict per parameter with the posterior
mean/sdand 5/50/95% quantiles, plus the recommended convergence diagnostics:r_hat(=rhat_max(), the max of the bulk and folded rank-normalized split-R-hats),ess_bulk,ess_tail, andmcse_mean(Vehtari et al. 2021). Declare convergence atr_hat < 1.01withess_bulk/ess_tailcomfortably in the hundreds.
- geweke_z(chain, first=0.1, last=0.5)[source]
Geweke convergence z-score comparing the start and end of a single chain (per parameter).
Tests stationarity within one chain (Geweke 1992): if the chain has converged, the mean of its first
firstfraction and its lastlastfraction agree, so the z-statistic(mean_a - mean_b) / sqrt(se_a^2 + se_b^2)– with autocorrelation-adjusted standard errors (the segment variance divided by its effective sample size) – is approximately standard normal.|z| < 2indicates convergence; a large|z|flags a chain still drifting. Returns one z per parameter. Complements the multi-chainsplit_rhat().