Reference / binference.Selection

binference.Selection

class binference.Selection(values, mode, *, scale='probability')

Per-bin detection probability (fractions) or exposure (rates), with its mode.

Parameters:

valuesarray_like (K,)

Strictly positive detection probabilities or exposures per bin.

mode{“on_measurement”, “on_truth”}

How selection enters the likelihood (see the module documentation); combined() builds the third mode.

scale{“probability”, “exposure”, “relative”}

Whether the values are detection probabilities, exposures or relative values. "probability" (default): values are detection probabilities in (0, 1]. "exposure": absolute positive values, such as the exposure of a rate model. "relative": only ratios between bins are known, which suffices for fractions but not for rates or totals.

Attributes:

valuesndarray (K,)

\(S_k\), the probability that an object in bin k is selected.

rowndarray (K,) or None

The factor applied to the likelihood columns (\(S_k\) on the truth, \(C_k\) combined, None on the measurement).

basisBasis or None

Set when the values are per component of a Basis (\(\phi_k\)-weighted averages) rather than per bin.

injectionstuple or None

For a selection measured by injections (from_injections()), a named tuple (injected, recovered, prior, smooth): counts per bin, the Beta prior and the step scale of the smooth model (or None). The selection is then uncertain, and inferred jointly with the population (DECISIONS #30, #80); values are its posterior means given the injections alone (independent Betas) or the mode of \(\mathrm{logit}\,S\) (smooth).

__init__(values, mode, *, scale='probability')

Methods

__init__(values, mode, *[, scale])
at_mean()	This selection fixed at its values, ignoring their uncertainty.
combined(on_truth, on_measurement[, bins, ...])	Selection on the truth and on the measurement at once (DECISIONS #8).
draw(n[, rng])	(n, K) posterior draws of \(S\) given the injections alone (independent Betas), floored at S_FLOOR so that none underflows to zero.
from_function(function, bins, mode, *[, ...])	A selection given as a function of the true value, averaged over each bin.
from_injections(z, detected, bins, mode, *)	A selection measured by injecting objects of known true value z.

Attributes

basis
injections
row
scale
values
K
mode	"on_measurement", "on_truth" or "combined", from row.

at_mean()

This selection fixed at its values, ignoring their uncertainty.

classmethod combined(on_truth, on_measurement, bins=None, *, scale='probability', tol=1e-06)

Selection on the truth and on the measurement at once (DECISIONS #8).

Parameters:

on_trutharray_like (K,) or callable

\(C\), the detection probability given the true value.

on_measurementarray_like (K,) or callable

\(P(d \in A \mid z)\), the probability that the measured data pass the cut given the true value.

binsBins or Basis, optional

Bins over which callable parts are averaged, in the measure coordinate; needed when either part is a callable (when both are, the product is averaged as a whole). With a Basis the result is per component, as for from_function().

scale{“probability”, “exposure”, “relative”}, optional

Whether the values of both parts are detection probabilities, exposures or relative values, as for Selection.

tolfloat

Quadrature tolerance for callable parts (see from_function()).

draw(n, rng=None)

(n, K) posterior draws of \(S\) given the injections alone (independent Betas), floored at S_FLOOR so that none underflows to zero.

Parameters:

nint

Number of draws.

rngint, numpy.random.Generator, or None

Random number generator.

classmethod from_function(function, bins, mode, *, scale='probability', tol=1e-06)

A selection given as a function of the true value, averaged over each bin.

function(z) returns the detection probability (or exposure) at points z (shape (M,) in 1-D, (M, ndim) on grids, labels for categories). Each bin takes its average in the measure coordinate, the within-bin shape of the population (DECISIONS #10, #47), by adaptive quadrature to tol relative to the largest bin average. With a Basis for bins, the averages are taken on its quadrature cells and weighted by each component (DECISIONS #47, #76).

Parameters:

functioncallable

Detection probability or exposure at points z.

binsBins or Basis

Bins over which function is averaged.

mode{“on_measurement”, “on_truth”}

How selection enters the likelihood, as for Selection.

scale{“probability”, “exposure”, “relative”}, optional

Whether the values are detection probabilities, exposures or relative values, as for Selection.

tolfloat, optional

Quadrature tolerance relative to the largest bin average.

classmethod from_injections(z, detected, bins, mode, *, prior=(1.0, 1.0), smooth=None)

A selection measured by injecting objects of known true value z.

Counts the injections per bin, \(n_k\), and those recovered, \(d_k\); with a \(\mathrm{Beta}(a, b)\) prior each \(S_k\) has the posterior \(\mathrm{Beta}(a + d_k, b + n_k - d_k)\) given the injections alone. With smooth the \(S_k\) are tied together by a second-order random walk on \(y_k = \mathrm{logit}\,S_k\), the log density gaining \(-\sum_k (y_{k-1} - 2y_k + y_{k+1})^2 / 2\tau^2\), which lends sparsely injected bins strength from their neighbours.

A selection on the truth is uncertain: NUTS, MAP (space="unconstrained"), Laplace and, for independent Betas and a conjugate prior, Gibbs infer it jointly with the population, where the catalogue informs the ratios between the \(S_k\) (their level comes from the injections; DECISIONS #10, #30, #79, #80); at_mean() gives a fixed selection at values, ignoring the uncertainty. A selection on the measurement cannot be inferred (the likelihoods’ cut already fixes it), and neither can a selection with a rates prior; pass at_mean() for both.

Parameters:

zarray_like, shape (n,) or (n, ndim)

True values of the injected objects.

detectedarray_like of bool, shape (n,)

Whether each injected object was recovered.

binsBins

The bins of the population.

mode{“on_truth”, “on_measurement”}

As for Selection.

prior(float, float)

Beta prior \((a, b)\) of every \(S_k\), both positive.

smoothfloat, optional

Step scale \(\tau\) of the random walk, in logit per bin (1-D bins only); None (default) keeps the \(S_k\) independent.

property mode

"on_measurement", "on_truth" or "combined", from row.