docs: better VI posterior and sampling methods how-to-guides - #1942
Merged
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1942 +/- ##
==========================================
- Coverage 87.80% 87.66% -0.14%
==========================================
Files 143 143
Lines 13435 14786 +1351
==========================================
+ Hits 11796 12962 +1166
- Misses 1639 1824 +185
Flags with carried forward coverage won't be shown. Click here to find out more. |
dgedon
reviewed
Jul 24, 2026
- name the learned quantity for NPE, NLE and NRE, and state that embedding networks are trained jointly with the estimator - define IID observations at first use and link the IID guide from the NLE paragraph - use "sequential (multiround)" consistently, and replace the SNPE_A/SNPE_B bullet with a neutral note on which variant each alias resolves to - trim the sampler-guide intro that duplicated the inference-method guide - add a sample_with -> posterior class table, so class names appear next to the argument that produces them - replace the uncheckable rejection-sampling precondition with the acceptance rate, its 1% warning threshold, and the option of a better proposal - name concrete diagnostics (R-hat and ESS, evaluate(), effective sample size from importance log-weights) instead of "inspect diagnostics" - explain the VI quality score: PSIS k-hat by default, or an R^2 with "prop" - note that VI posteriors have no log_prob_batched() - separate the train()/train_amortized() mode exclusivity from the ELBO note
Follows the sample_with table with the typed dataclass that configures each posterior class, and notes that the older per-sampler dictionaries plus mcmc_method / vi_method are deprecated. Links the PosteriorParameters guide.
Makes every criterion in the intro explicitly a sampler criterion, and ties the repeated-observation case to the fixed-observation and amortized VI sections of this guide, so the paragraph does not read as inference-method guidance.
- DirectPosterior wraps a trained density estimator and takes no potential_fn, so name the four classes that can be built from one instead of "every class" - mcmc_method and vi_method only warn at non-default values, unlike the per-sampler dictionaries which warn whenever passed - the ArviZ guide shows how to get samples into an InferenceData container rather than computing R-hat or ESS, so attribute those to ArviZ itself
FMPE and NPSE estimate the posterior but are not part of the NPE family in sbi's taxonomy, and their sampling works by integrating an ODE or SDE, so the latency and sequential-workflow statements about NPE do not carry over. Point readers at the dedicated guide from the inference-method guide, and from the sampler guide where the ode/sde choice belongs.
Open with the general context of why sampling differs per method, then route the reader by which inference method they used, then show how to set the sampler, and only then expose the potential-function API as the low-level interface. Also correct the rejection-sampling acceptance rate claim: the rate is not returned by RejectionPosterior.sample(), which discards it; the sub-1% warning is the only user-facing signal.
VI had no guide of its own, so the sampler guide was the only place documenting train() vs train_amortized(), the vi_method options and evaluate(). Move that content into its own how-to and link to it from the sampler guide, the abstraction-levels and PosteriorParameters guides, and the implemented-methods tutorial.
It was registered in the sampling toctree but missing from the landing page list.
The dataclass type already determines the posterior class, so passing sample_with alongside it is superfluous. Present the two layers as sample_with for the simple case and PosteriorParameters for flexibility and type checking, and note that FMPE and NPSE still need sample_with because VectorFieldPosteriorParameters does not encode the integrator.
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
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.
As discussed in #1765, the how-to guides around sampling methods and VI are a bit outdated and in parts misleading. This PR reworks them.
Restructure the sampler guide
09_sampler_interfacewas accurate but hard to act on: it opened abruptly and mixedrecommendations, configuration and low-level API across a flat list of sections. It now
follows the path a stuck user actually takes:
posterior directly so sampling is a forward pass, while NLE and NRE give a score
proportional to the log posterior and need an extra algorithm.
NPE/FMPE/NPSE: nothing to choose, plus the two exceptions (leakage, evaluable
likelihood). NLE/NRE: start with MCMC, then branch to VI, rejection or importance
sampling by the symptom you have.
build_posterior(sample_with=...)withPosteriorParameters.interface, including building the sampler classes on a potential directly to use a
non-prior proposal.
Give VI its own guide
VI had no guide of its own, so the sampler guide was the only place documenting
$\hat{k}$ , SIR refinement, sequential NLE with VI, and amortized VI. The
train()vstrain_amortized(), thevi_methodoptions andevaluate(). That contentmoves to a new
26_variational_inferenceguide, which covers fixed-observation VI, qualitycontrol with
sampler guide now links to it, as do the abstraction-levels and
PosteriorParametersguides and the implemented-methods tutorial.
Corrections
posterior geometry, proposal overlap, computational budget, repeated-observation needs
and diagnostics.
RejectionPosterior.sample()discardsthe rate returned by
rejection_sample(), so it cannot be read from the documentedworkflow; the sub-1%
logging.warningis the only user-facing signal. Callsbi.samplers.rejection.rejection_sample()directly if the number itself is needed.train()andtrain_amortized().toctree but missing from the list.
Every API name, keyword argument, default and behavioural claim in the new text was checked
against the source rather than carried over on trust.
Docs-only change, so no CHANGELOG entry and no tests. Built locally with Sphinx; all
cross-references resolve.
Claude Code assisted with the restructure and with verifying the API claims.
Closes #1765