Reference / binference.samplers.Laplace

binference.samplers.Laplace

class binference.samplers.Laplace(model, *, importance=True, n_proposals=None, df=5.0, inflate=1.0, step=1e-05, rng=None, progress=False)

Gaussian (Laplace) approximation in unconstrained coordinates.

The posterior mode in unconstrained coordinates is found with L-BFGS, the Hessian is computed from central differences of the exact gradient, and draws from the Gaussian are mapped to the simplex (or rates). With importance=True (default) the draws are corrected towards the exact posterior by Pareto-smoothed importance resampling; the Pareto shape k_hat (in info) diagnoses whether the correction is reliable: below min(1 - 1 / log10(S), 0.7) for S proposals (Vehtari et al. 2024), in info["k_hat_threshold"]. Without a reliable correction the result is flagged approximate=True.

The approximation is excellent for well-populated bins with many objects and poorer for nearly empty bins, whose log-fractions have long tails.

Parameters:

modelPopulationModel

importancebool

Apply PSIS importance resampling.

n_proposalsint, optional

Number of proposals for importance resampling (default 2 * n_samples); without it the draws are the proposals themselves.

dffloat or None

Degrees of freedom of the multivariate Student-t importance proposal (default 5); None uses the Gaussian itself. Heavier tails make the importance correction more robust.

inflatefloat

Scale applied to the proposal’s standard deviations.

stepfloat

Relative step for the finite-difference Hessian.

rngint, numpy.random.Generator, or None

For the proposals and the resampling.

progressbool

Accepted for a common signature; unused.

Notes

In ILR coordinates the posterior of nearly empty bins has a long one-sided tail, so for more than a handful of bins the importance correction often fails (k_hat above the threshold) and the result is flagged approximate: the Laplace approximation is then a fast summary of well-populated bins, not a replacement for NUTS.

__init__(model, *, importance=True, n_proposals=None, df=5.0, inflate=1.0, step=1e-05, rng=None, progress=False)

Methods

__init__(model, *[, importance, ...])
mode_and_covariance()	Mode, covariance and Hessian in unconstrained coordinates.
run([n_samples])	Draw n_samples (approximately) from the posterior.
unsupported(model)	Why the engine cannot run on model, or None when it can.

Attributes

approximate
joint	whether the engine infers a selection from injections or a tallied response jointly (DECISIONS #30, #80, #81)
markov	whether its draws are Markov chains, described by R-hat and ESS
name

joint = True

whether the engine infers a selection from injections or a tallied response jointly (DECISIONS #30, #80, #81)

mode_and_covariance()

Mode, covariance and Hessian in unconstrained coordinates.

run(n_samples=4000)

Draw n_samples (approximately) from the posterior.

Parameters:

n_samplesint, optional

Draws returned in total.