Reference / binference.simulate.prior_predictive

binference.simulate.prior_predictive

binference.simulate.prior_predictive(prior, bins, n_objects=None, *, noise=(0.05, 0.2), selection=None, selection_mode=None, max_objects=1000000.0)

A simulator simulate(rng) -> (likelihoods, truth) drawing populations from a prior.

Each call draws a population from prior, objects uniformly within bins from it, and Gaussian measurements with the given noise (in units of the bin coordinate), and returns the likelihoods with the selection attached and the true fractions \(\rho\) (or rates \(\lambda\) for a rate prior). Intended for binference.validation.sbc() and binference.validation.coverage(). One-dimensional bins only.

Parameters:

priorPopulationPrior

Prior on fractions, or on rates (e.g. GammaRates, which then needs an informative rate).

binsBins

One-dimensional bins.

n_objectsint, optional

Number of observed objects (after selection), for priors on fractions (default 200). For rates the number is drawn: \(N \sim \mathrm{Poisson}(S\cdot\lambda)\), i.e. \(\Lambda\,S\cdot\rho\), so n_objects must not be given. A draw with no object is discarded and the population drawn again, which conditions the joint draw on \(N \ge 1\) and leaves the ranks of SBC uniform.

noisefloat or (lo, hi)

Measurement standard deviation, fixed or drawn uniformly per object.

selectionarray_like (K,), optional

Selection per bin: detection probabilities in (0, 1] for fractions, exposures (any positive values) for rates. Without it, every object is observed (unit exposure for rates).

selection_mode{“on_truth”, “on_measurement”}

Required with selection. "on_truth": an object is kept with a probability proportional to selection of its true bin, and the likelihoods carry Selection(selection, "on_truth"). "on_measurement": it is kept with a probability proportional to selection of the bin its measured value falls in (values beyond the range count in the end bins), and the likelihoods carry an "on_measurement" selection whose \(S_k\) is the bin average of \(\sum_j T_j P(d \in j \mid z)\) over the noise distribution, with \(T\) the given values.

max_objectsfloat

For rates, the largest expected number of objects \(S\cdot\lambda\) a draw may have. Every object is simulated, so a draw beyond it raises (as the vague default GammaRates does).

Returns:

callable

simulate(rng) returning (likelihoods, truth).

Notes

Objects are kept with probability selection / max(selection) until enough are observed; only the ratios matter for which objects are kept, while the absolute values set the selection attached to the likelihoods and, for rates, the expected number of objects.