mixle.ppl.summarize module

Posterior summarization for the mixle PPL: highest-density intervals and an ArviZ-style table.

After an MCMC / ensemble fit you want a compact, readable report of each parameter’s posterior. The equal-tailed credible interval in RandomVariable.summary() is fine for symmetric posteriors; hdi() gives the highest-density interval (the narrowest interval holding the mass, the right choice for skewed or bounded posteriors), and posterior_summary() assembles the mean / sd / HDI together with the convergence diagnostics (effective sample size, R-hat) into one per-parameter dict.

hdi(samples, prob=0.94)[source]

Highest-density interval: the narrowest interval containing prob of the posterior mass.

For a unimodal posterior this is the shortest (low, high) such that P(low <= x <= high) = prob; unlike an equal-tailed interval it tracks an asymmetric or bounded posterior correctly.

Parameters:
Return type:

tuple[float, float]

posterior_summary(fitted, *, hdi_prob=0.94)[source]

Per-parameter posterior summary table for a fitted PPL model (best after how='mcmc').

Returns a fixed per-parameter schema with mean, sd, hdi_low, hdi_high, ess, ess_tail, r_hat, mcse, diagnostic_status, and diagnostic_error. mean/sd come from the fit’s own summary; the HDI is computed from the posterior draws (when the fit exposes them); ess (effective sample size) and r_hat (Gelman-Rubin, multi-chain) come from the sampler’s diagnostics when present; mcse is the Monte Carlo standard error of the mean, sd / sqrt(ess) – the parameter number’s own noise floor, published WITH the number instead of dropped (STAT-RR17-11). A point fit (em/map) yields just mean/sd.

diagnostic_status semantics (STAT-RR17-11 – “ok” used to mean only “the ESS call did not raise”, so a one-chain fit with r_hat=None or NaN split-R-hat still published parameter numbers under “ok”):

  • "ok" – ess, ess_tail, mcse are finite, a finite multi-chain r_hat exists, AND the values clear the standard convergence thresholds: split R-hat <= 1.01, bulk and tail ESS >= 100 (STAT-RR22-13 – finiteness alone labeled R-hat-1.363 fits “ok”). The ONLY promotable state.

  • "unconverged-by-diagnostics" – finite diagnostics that FAIL a threshold; the error names the failing number. Not promotable: run longer or with more chains.

  • "divergent-transitions" – the fit recorded post-warmup NUTS divergences (STAT-RR23-12: 15- and 16-divergence funnel fits read ok on clean R-hat/ESS). Not promotable: divergences are direct evidence of unexplored posterior geometry; reparameterize or raise target_accept.

  • "single-chain-mixing-unassessable" – ESS computed, but one chain cannot assess mixing (no R-hat); run >= 2 chains before treating the summary as converged evidence.

  • "unusable" – a diagnostic evaluated non-finite (NaN/inf ESS or R-hat).

  • "unavailable" / "failed" – draws or diagnostics missing / raised.

Parameters:

  • fitted (RandomVariable)

  • hdi_prob (float)

Return type:

dict[str, dict[str, Any]]