mixle.ppl.diagnostics module¶
Predictive model-comparison diagnostics for the mixle PPL: WAIC and PSIS-LOO.
Both estimate the expected log pointwise predictive density (elpd) – how well a fitted Bayesian model
predicts new data – from the pointwise log-likelihood matrix loglik of shape (n_draws, n_obs)
(the log-density of each observation under each posterior draw of the parameters).
waic– the Widely Applicable Information Criterion (Watanabe):elpd = lppd - p_waicwith the effective parameter countp_waicthe per-observation posterior variance of the log-likelihood.psis_loo– Pareto-Smoothed Importance-Sampling Leave-One-Out cross-validation (Vehtari, Gelman & Gabry 2017). Importance-reweights the full-data posterior to each leave-one-out posterior, smoothing the heavy importance-weight tail with a generalized-Pareto fit; it reports the diagnostic shapekhat(values above ~0.7 flag unreliable estimates).
Both return results on the deviance scale (waic/loo = -2 * elpd, lower is better) with a
standard error, matching the conventions of Stan / ArviZ / the R loo package.
- split_rhat(draws)[source]
Maximum rank-normalized and folded split-R-hat for one parameter.
drawsmust be a finite(n_chains, n_draws)matrix with at least two chains and four draws per chain. Splitting catches within-chain non-stationarity; folding about the pooled median also catches scale mismatch. Values within ~0.01 of 1.0 indicate convergence; > 1.01 is a warning. Constant chains have no estimable scale and returnNaNrather than a healthy-looking value.
- bulk_ess(draws)[source]
Bulk ESS of split rank-normalized draws; constant chains return
NaN.
- tail_ess(draws)[source]
Tail ESS from split 5% and 95% quantile indicators; unavailable cases return
NaN.
- convergence_diagnostics(draws)[source]
Return modern convergence metrics plus an explicit availability receipt.
Every unavailability is a RECEIPT, not an exception: a metric that cannot be computed for these draws comes back
NaN, is listed underunavailable, and gets a plain-language entry inunavailable_because. In particular a single chain – the default configuration of every sampling route – receiptssplit_rhat(which compares independent chains) while still returning the finite single-chainbulk_ess/tail_essestimates, instead of raising the 2-chainValueErrorfor one cause and receipting the other (t5 wave-3). Malformed input (wrong shape, NaN/Inf draws, too few draws to split) still raises.
- waic(loglik)[source]
Return the WAIC of a
(n_draws, n_obs)pointwise log-likelihood matrix.
- psis_loo(loglik)[source]
Return PSIS-LOO of a
(n_draws, n_obs)pointwise log-likelihood matrix.
- loo(loglik)[source]
PSIS-LOO under its conventional short name (see
psis_loo()).
- loo_stacking_weights(pointwise_lpd, iters=2000, tol=1.0e-10, *, return_result=False)[source]
Return LOO stacking weights (Yao, Vehtari, Simpson & Gelman, 2018).
pointwise_lpdis an(n_obs, K)matrix of per-model pointwise LOO log-predictive densities (each column ispsis_loo(model_k)["pointwise"]). The returned simplex weightswmaximize the LOO log-score of the weighted predictive distribution,sum_i log(sum_k w_k * exp(lpd_ik)). This is concave inwand solved here by the standard mixture-weight EM update (no external optimizer), which respects the simplex by construction. By default this compatibility surface returns only the weights. Setreturn_result=Trueto receive the weights together with convergence, iteration, objective, and termination metadata.
- loo_stack(logliks, *, iters=2000, tol=1.0e-10)[source]
Stack K candidate models by LOO predictive performance.
logliksis a sequence of(n_draws_k, n_obs)pointwise log-likelihood matrices over the same, aligned observations. Returns the stackingweights, the(n_obs, K)per-model pointwise LOO densities, each model’selpd_loo, the actually achievedstacked_elpd_loo, and an optimizer receipt. A finite iteration limit need not reach the exact optimum.