feat(diagnostics): E-BFMI, treedepth saturation, stability plot, reserved-prefix doc - #224
Open
thomaspinder wants to merge 1 commit into
Open
Conversation
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## feat/142-convergence-report #224 +/- ##
===========================================================
Coverage 95.2% 95.3%
===========================================================
Files 47 48 +1
Lines 3402 3495 +93
Branches 420 431 +11
===========================================================
+ Hits 3242 3334 +92
Misses 114 114
- Partials 46 47 +1 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
thomaspinder
force-pushed
the
feat/142-convergence-report
branch
2 times, most recently
from
July 29, 2026 21:06
7d32bea to
daf27e5
Compare
Three follow-ups cut from the convergence report in #142. E-BFMI and max-treedepth saturation join the report (#180). Both are read from the post-warmup `sample_stats` only; energy shares a name across backends, treedepth needs a map (`reached_max_treedepth` in PyMC, `maxdepth_reached` in nutpie). Thresholds are `ebfmi_warn=0.3` (Betancourt 2016) and `treedepth_warn_rate=0.01`, the latter chosen rather than sourced: a handful of deep trees in a long run costs wall-clock time and nothing else, so the report stays silent below one transition in a hundred. Both warn and neither fails — they are efficiency pathologies, remediable by changing the sampler or the parameterisation, and distinct from a divergence or an unmixed R-hat, which say the draws are wrong. The `v{i}_` posterior-variable prefix is now documented as reserved on the `VolatilityProcess` protocol, where adapter authors will see it (#182); previously it was stated only in ADR-0008, so a hand-registered `v2_gdp` would have been silently routed to the volatility block. `plot_stability` draws the spectral-radius posterior beside the companion roots on the unit circle, reached as `report.stability.plot()` (#179). The eigenvalues it scatters are stored on `StabilitySummary` as a chain-pooled, strided subset capped at 200 draws, computed from the one eigendecomposition the radii already require: keeping the full spectrum would put ~15 MB on a frozen result for a large system, and the panel cannot resolve more points than that anyway. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Egjd7ToFeb9TQqFnfRQZxV
thomaspinder
force-pushed
the
feat/179-180-182-convergence-followups
branch
from
July 29, 2026 21:59
059164a to
62561e8
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three follow-ups on the convergence-report branch (#176), stacked on
feat/142-convergence-report:reached_max_treedepthpymc /maxdepth_reachednutpie, warmup groups excluded), coded messages, configurable thresholds, andNonefields when sampler stats are absent (conjugate fits — no status degradation). Both are warnings, never failures: efficiency pathologies, remediable without changing the model — the docstring and ADR argue the distinction. Verified against a real nutpie fit.StabilitySummary.plot()— spectral-radius histogram with a unit-root line plus companion eigenvalues on the complex plane with the unit circle. Storage decision: the summary now retains a capped (≤200 draws, deterministic stride) chain-pooled eigenvalue subset, computed in the same pass that already produced the radii — zero extra compute, no 15 MB frozen-result bloat, and the house no-arg.plot()convention holds.VolatilityProcessprotocol docstring now names thev{i}_posterior-variable prefix as reserved for volatility latents, pointing adapter authors atposterior_var_names().Closes #179
Closes #180
Closes #182
Gates
154 targeted tests green (+29 new); branch fast suite 670 passed; slow real-NUTS test green; ruff/ty clean.
🤖 Generated with Claude Code
https://claude.ai/code/session_01Egjd7ToFeb9TQqFnfRQZxV