Reference / binference.Likelihoods

binference.Likelihoods¶

class binference.Likelihoods(values, bins=None, *, representation='density', weights=None, selection=None, selection_mode=None, drop_empty=False, log=False, fractional_weights=False)[source]¶

Bin-averaged per-object likelihoods \(L_{ik} \propto p(d_i \mid z_i \in B_k)\).

This container holds the (N, K) matrix of likelihoods of every object for every bin, together with the Bins, optional object weights, an optional selection function, and provenance metadata. Rows are stored normalised to a maximum of one (their scales never affect inference on the population); the per-row log-scales are kept so that absolute log-likelihoods (evidences, cross-validation scores) can be recovered.

Use the from_* constructors to convert posteriors (with their interim prior), posterior samples, analytic measurement models, response matrices or classifier outputs into likelihoods. See Prepare your inputs for the conventions.

Parameters:

valuesarray_like or sparse matrix, shape (N, K): Non-negative likelihood values. Rows with all zeros are invalid.
binsBins or Basis, optional: The support. Defaults to Bins.categories(K). With a Basis the values are per reporting bin (the likelihood taken as flat within each) and are projected onto its components (DECISIONS #76).
representation{“density”, “mass”}: Values per unit volume ("density") or integrated over each bin ("mass"). "density" (default): each value is the likelihood evaluated in (or averaged over) the bin. "mass": each value is the likelihood integrated over the bin (e.g. CDF differences); it is divided by the bin volume. The distinction only matters for unequal bin volumes.
weightsarray_like, shape (N,), optional: Positive integer multiplicities: an object with weight 3 counts as three identical objects (as produced by compress()).
fractional_weightsbool: Allow non-integer weights. They define a weighted pseudo-likelihood, not the likelihood of any data set, so posteriors from it are not proper posteriors; a warning says so (DECISIONS #1).
selectionarray_like (K,), callable or Selection, optional: Detection probability (or exposure) per bin, used by models unless overridden; see Selection and rates.
selection_mode{“on_measurement”, “on_truth”}, optional: Whether the selection acts on the measurement or on the truth; required with an array or callable selection. "on_measurement": objects are selected on their measured data (or the likelihoods already include the detection probability); "on_truth": they are detected with a probability that depends on their true value. See Selection.
drop_emptybool: Drop all-zero rows with a warning instead of raising.
logbool: If True, values are log-likelihoods (-inf allowed).

Examples

>>> import numpy as np, binference
>>> bins = binference.Bins.linear(0, 1, 4)
>>> lk = binference.Likelihoods(np.array([[1, 2, 1, 0], [0, 1, 3, 1.0]]), bins)
>>> lk.N, lk.K
(2, 4)

__init__(values, bins=None, *, representation='density', weights=None, selection=None, selection_mode=None, drop_empty=False, log=False, fractional_weights=False)[source]¶

Methods

`__init__`(values[, bins, representation, ...])
`compress`([decimals])	Merge identical rows into weighted rows.
`from_binned`(response, *[, counts, values, ...])	Binned measurements: counts per measured bin, or measured values, and a response.
`from_density`(density, bins, *[, kind, ...])	Likelihoods from per-object densities over the bin coordinate.
`from_gaussian`(mean[, sigma, bins, cov, ...])	Likelihoods for Gaussian measurements \(d_i \sim \mathcal N(z, \sigma_i^2)\).
`from_log`(log_values[, bins])	Build from log-likelihoods (`-inf` marks zero likelihood).
`from_samples`(samples, bins, interim, *[, ...])	Build likelihoods from per-object posterior samples (DECISIONS #31).
`from_table`(values, bins, *[, kind, interim, ...])	Likelihoods from a table of per-object values on the bins.
`log_evidence_terms`(rho)	Per-object absolute log marginal likelihoods \(\log(L_i\cdot\rho)\), unweighted.
`on_basis`(basis)	These likelihoods, on `basis.bins` or its quadrature cells `basis.grid`, as likelihoods of the components of `basis`.
`sample_variance`(rho)	Monte Carlo error of likelihoods built by `from_samples()`, at fractions `rho`.
`stack`([interim, interim_representation])	Naive "stacked" population estimate: the weighted mean of per-object posteriors.
`subset`(idx)	Rows `idx` (any NumPy index) as a new object.
`to_dense`()	Copy with dense storage.
`to_sparse`([rtol])	Copy with sparse CSR storage, dropping entries below `rtol` (relative to row max).
`toarray`()	Dense copy of the row-normalised values.
`with_selection`(selection[, selection_mode])	Copy with a (new) selection function attached.
`with_weights`(weights[, fractional_weights])	Copy with new object weights.

Attributes

`K`	Number of bins (columns).
`N`	Number of objects (rows).
`W`	Total weight `sum_i w_i` (the effective number of objects).
`basis`	The `Basis` whose components the columns are, or `None`.
`bins`	The `Bins` the likelihoods are defined over.
`is_sparse`	Whether values are stored as a sparse CSR array.
`log_scale`	Per-object log normalisation: `log L_ik = log values_ik + log_scale_i`.
`nnz`	Number of stored (non-zero) entries.
`selection`	Selection function attached to the data, if any.
`shape`	`(N, K)`; with `len` and row indexing, it lets scikit-learn split objects.
`values`	Row-normalised likelihood matrix (dense ndarray or sparse CSR array).
`weights`	Per-object weights `(N,)`.

property K¶: Number of bins (columns).

property N¶: Number of objects (rows).

property W¶: Total weight sum_i w_i (the effective number of objects).

property basis¶

The Basis whose components the columns are, or None.

With a basis, bins are its components and basis.bins the reporting bins.

property bins¶: The Bins the likelihoods are defined over.

compress(decimals=None)[source]¶

Merge identical rows into weighted rows.

Rows are compared after row normalisation, optionally rounded to decimals. Weights add and log-scales are combined, so total absolute log-likelihoods are preserved exactly when decimals is None; with rounding, each group is represented by its first row. Inference on the population is unchanged; Gibbs sampling then draws multinomial counts per unique row. Sparse storage stays sparse. Always returns a new object.

Parameters:

decimalsint, optional: Round rows to this many decimals before merging; None merges exact duplicates.

classmethod from_binned(response, *, counts=None, values=None, fractional_weights=False)[source]¶

Binned measurements: counts per measured bin, or measured values, and a response.

Every object measured in bin \(j\) has likelihood row \(R_{j\cdot}\) (Response), and rows are weighted by the counts. The truth bins are the response’s. The efficiency (the column sums of \(R\)) becomes the selection function in "on_measurement" mode, because the rows already include it. For a response tallied from events, which is inferred with the population, the rows and the efficiency are its posterior means, so a measured bin without tallied events still has a row (DECISIONS #81). This covers unfolding (a detector response) and classifier outputs binned by score (Response.from_labelled(), DECISIONS #29).

Parameters:

responseResponse: The response of the measurement.
countsarray_like (J,), optional: Observed objects per measured bin (integers).
valuesarray_like, optional: Measured value of each object, binned by Response.index(); values outside the measured bins are left out with a warning. Give exactly one of counts and values.
fractional_weightsbool: Accept non-integer (for example weighted) counts, which give a pseudo-likelihood.

classmethod from_density(density, bins, *, kind=None, interim=None, interim_representation=None, log=False, tol=0.001, max_depth=12, n_sub=None, weights=None, selection=None, selection_mode=None, drop_empty=False, fractional_weights=False, warn_outside=True)[source]¶

Likelihoods from per-object densities over the bin coordinate.

density is either a vectorised function, where density(points) returns an (N, M) array of values (log-values with log=True) at M points of shape (M,) (1-D) or (M, ndim), or a sequence of distribution objects with logpdf, pdf, logcdf or cdf (e.g. frozen scipy.stats). Say what they are: kind="likelihood" or interim= for posteriors, as in from_table().

Likelihoods are averaged over each bin uniformly in the measure coordinate, the within-bin population shape; posteriors are integrated over each bin in z and divided by the interim prior’s bin masses. On 1-D bins, distributions with a cdf are integrated exactly where the result is a mass (posteriors, or likelihoods on a linear measure), in log space so that far tails keep their precision.

Other integrals use adaptive quadrature: each bin is refined until the estimated error is below tol relative to each row’s largest bin average, splitting cells at most max_depth times; n_sub instead fixes n_sub Gauss-Legendre points per bin and axis. The fraction of each distribution’s mass outside the active bins is recorded in meta["outside_fraction"] on 1-D bins (see from_gaussian() for warn_outside).

Parameters:

densitycallable or sequence of distributions: Per-object densities of z, as above.
binsBins or Basis: Grid bins. With a Basis, likelihoods of its components.
kind{“likelihood”}, optional: The densities are likelihoods. Exactly one of kind and interim.
interimDensity, “flat”, callable, distribution or array_like (K,), optional: The prior the posteriors were computed with, read by Density.coerce().
interim_representation{“mass”, “density”}, optional: How an array interim is read (see from_table()).
logbool, optional: The function returns logarithms.
tolfloat, optional: Relative tolerance of the adaptive quadrature over each bin.
max_depthint, optional: Most refinements of the adaptive quadrature.
n_subint, optional: Fixed Gauss-Legendre points per bin and axis in place of adaptive quadrature.
weightsarray_like (N,), optional: Integer multiplicity of each object; None gives every object weight one.
selectionarray_like (K,), callable or Selection, optional: Detection probability or exposure per bin; None means no selection.
selection_mode{“on_measurement”, “on_truth”}, optional: Whether the selection acts on the measurement or on the truth; required with an array or callable selection.
drop_emptybool, optional: Drop objects with zero likelihood in every bin, with a warning, instead of raising.
fractional_weightsbool, optional: Accept non-integer weights, which give a pseudo-likelihood.
warn_outsidebool, optional: Warn when many objects have most of their likelihood outside the bins.

classmethod from_gaussian(mean, sigma=None, bins=None, *, cov=None, weights=None, selection=None, selection_mode=None, drop_empty=False, fractional_weights=False, tol=0.001, max_depth=12, warn_outside=True)[source]¶

Likelihoods for Gaussian measurements \(d_i \sim \mathcal N(z, \sigma_i^2)\).

Bin averages are exact CDF differences (stable in the far tails) on axes with a linear measure; on other axes the likelihood is averaged uniformly in the measure coordinate by adaptive quadrature to tol with at most max_depth refinements (see from_density()). For N-D grids, measurement errors are independent per axis (mean and sigma of shape (N, ndim)) unless cov gives each object’s full covariance; correlated Gaussians are averaged over each bin by adaptive cubature in log space, to tol, in any number of dimensions (DECISIONS #25). Each object’s fraction of mass outside the active bins is recorded in meta["outside_fraction"]; warn_outside warns when more than 10% of the objects have more than 90% of their mass outside.

Parameters:

meanarray_like, shape (N,) or (N, ndim): Measured values.
sigmafloat or array_like, shape (N,) or (N, ndim): Measurement uncertainties (strictly positive).
binsBins or Basis: Grid bins. With a Basis, likelihoods of its components (DECISIONS #76).
covarray_like, shape (ndim, ndim) or (N, ndim, ndim), optional: Full covariance matrices (symmetric positive definite), in place of sigma.
tolfloat, optional: Relative tolerance of the adaptive quadrature over each bin.
max_depthint, optional: Most refinements of the adaptive quadrature.
warn_outsidebool, optional: Warn when many objects have most of their likelihood outside the bins.
weightsarray_like (N,), optional: Integer multiplicity of each object; None gives every object weight one.
selectionarray_like (K,), callable or Selection, optional: Detection probability or exposure per bin; None means no selection.
selection_mode{“on_measurement”, “on_truth”}, optional: Whether the selection acts on the measurement or on the truth; required with an array or callable selection.
drop_emptybool, optional: Drop objects with zero likelihood in every bin, with a warning, instead of raising.
fractional_weightsbool, optional: Accept non-integer weights, which give a pseudo-likelihood.

classmethod from_log(log_values, bins=None, **kwargs)[source]¶

Build from log-likelihoods (-inf marks zero likelihood).

Parameters:

log_valuesarray_like, shape (N, K): Log-likelihoods.
binsBins or Basis, optional: The support; None gives categories.
**kwargs: Further arguments of Likelihoods.

classmethod from_samples(samples, bins, interim, *, sample_weights=None, interim_representation=None, weights=None, selection=None, selection_mode=None, sparse=None, drop_empty=False, fractional_weights=False, min_samples=20, floor=0.0, keep_samples=True, warn_outside=True)[source]¶

Build likelihoods from per-object posterior samples (DECISIONS #31).

One Monte Carlo estimator, \(\hat L_{ik} \propto \frac1S \sum_s w_s\,\mathbb 1[z_s \in B_k]\,T'(z_s) / \pi(z_s)\), averaged over each bin in the measure coordinate:

when the interim prior is known only per bin ("flat", masses or densities) this is the weighted count divided by the interim mass, \(L_{ik} \propto c_{ik} / \Pi_k\);
when it can be evaluated at points (a function or a distribution) each sample is weighted by \(T'(z_s)/\pi(z_s)\), which is exact when the interim prior varies within bins.

Samples drawn from a likelihood are samples under Density.flat("z"). The per-object effective number of samples inside the bins and the fraction outside are stored in meta; the sums behind the estimator are kept so that sample_variance() can measure its Monte Carlo error at a fitted population.

Parameters:

samplesarray_like or sequence of arrays: For 1-D bins: an (N, S) array or a list of N 1-D arrays (ragged allowed). For N-D grids: (N, S, ndim) or a list of (S_i, ndim) arrays.
binsBins or Basis: Target bins (grids only). With a Basis, likelihoods of its components (DECISIONS #76).
interimDensity, “flat”, callable, distribution or array_like (K,): Prior under which the samples were drawn, read by Density.coerce(). There is deliberately no default: samples drawn under an informative prior must have it divided out.
interim_representation{“mass”, “density”}, optional: How an array interim is read (see from_table()).
sample_weightsarray_like or sequence of arrays, optional: Importance weights for the samples (same layout as samples).
sparsebool, optional: Store the result sparsely. Defaults to sparse when fewer than 10% of entries are non-zero (_kernels.SPARSE_FILL; DECISIONS #77).
min_samplesint: Warn if more than 10% of the objects have fewer effective samples inside the bins than this (audit I-23).
floorfloat: Pseudo-samples added to every object, spread over the bins in proportion to the interim prior: a Dirichlet floor that keeps bins no sample reached from having zero likelihood. Off by default.
keep_samplesbool: Keep the samples inside the bins and their weights, so that PopulationResult.sample_values() resamples them within the drawn bin (DECISIONS #50); False saves that copy of the samples.
warn_outsidebool: Warn when many objects have most of their samples outside the bins (see from_gaussian()).
weightsarray_like (N,), optional: Integer multiplicity of each object; None gives every object weight one.
selectionarray_like (K,), callable or Selection, optional: Detection probability or exposure per bin; None means no selection.
selection_mode{“on_measurement”, “on_truth”}, optional: Whether the selection acts on the measurement or on the truth; required with an array or callable selection.
drop_emptybool, optional: Drop objects with zero likelihood in every bin, with a warning, instead of raising.
fractional_weightsbool, optional: Accept non-integer weights, which give a pseudo-likelihood.

classmethod from_table(values, bins, *, kind=None, interim=None, representation=None, interim_representation=None, log=False, weights=None, selection=None, selection_mode=None, drop_empty=False, fractional_weights=False)[source]¶

Likelihoods from a table of per-object values on the bins.

Say what the table holds: kind="likelihood" for likelihoods, or interim= for posteriors computed under that interim prior. Posteriors are converted with \(L_{ik} \propto P_{ik} / \Pi_k\), where \(P_{ik}\) is the posterior mass of object i in bin k and \(\Pi_k\) the interim prior’s mass; using posteriors as likelihoods would count the interim prior twice.

Parameters:

valuesarray_like or sparse matrix, shape (N, K): Non-negative values (rows need not be normalised).
binsBins or Basis: The bins the values are tabulated on. With a Basis, likelihoods of its components (DECISIONS #76).
kind{“likelihood”}, optional: The values are likelihoods. Exactly one of kind and interim.
interimDensity, “flat”, callable, distribution or array_like (K,), optional: The prior the posteriors were computed with, read by Density.coerce().
representation{“mass”, “density”}, optional: Values per bin ("mass") or at or averaged over the bin ("density"). Defaults to "density" for likelihoods and "mass" for posteriors, their usual forms.
interim_representation{“mass”, “density”}, optional: How an array interim is read. Required for arrays on bins of unequal volume, where the two readings differ.
logbool, optional: The values are logarithms (-inf allowed; dense only).
weightsarray_like (N,), optional: Integer multiplicity of each object; None gives every object weight one.
selectionarray_like (K,), callable or Selection, optional: Detection probability or exposure per bin; None means no selection.
selection_mode{“on_measurement”, “on_truth”}, optional: Whether the selection acts on the measurement or on the truth; required with an array or callable selection.
drop_emptybool, optional: Drop objects with zero likelihood in every bin, with a warning, instead of raising.
fractional_weightsbool, optional: Accept non-integer weights, which give a pseudo-likelihood.

property is_sparse¶: Whether values are stored as a sparse CSR array.

log_evidence_terms(rho)[source]¶

Per-object absolute log marginal likelihoods \(\log(L_i\cdot\rho)\), unweighted.

Parameters:

rhondarray (K,): Population fractions.

property log_scale¶: Per-object log normalisation: log L_ik = log values_ik + log_scale_i.

property nnz¶: Number of stored (non-zero) entries.

on_basis(basis)[source]¶

These likelihoods, on basis.bins or its quadrature cells basis.grid, as likelihoods of the components of basis.

The likelihood is taken as flat within each of its bins, so \(L_{ik} = \sum_q L_{iq} M_{qk}\) with \(M\) the components’ masses in those bins; constructors that know the likelihood within bins (from_gaussian(), from_density(), from_samples()) do this on the quadrature cells when given the Basis directly. A selection is carried over to the components.

Parameters:

basisBasis: Basis whose bins or grid these likelihoods are on.

sample_variance(rho)[source]¶

Monte Carlo error of likelihoods built by from_samples(), at fractions rho.

Returns the per-object relative variance \(V_i(\rho)\) of the estimate of \(L_i\cdot\rho\) and the effective number of samples under rho. Summed over objects, \(\sum_i V_i\) is about the bias it puts in the total log-likelihood (Jensen); values above about one call for more samples (DECISIONS #31).

Parameters:

rhoarray_like (K,): Population fractions.

property selection¶

Selection function attached to the data, if any.

See Selection.

property shape¶: (N, K); with len and row indexing, it lets scikit-learn split objects.

stack(interim=None, interim_representation=None)[source]¶

Naive “stacked” population estimate: the weighted mean of per-object posteriors.

Posteriors are formed under interim: by default the interim prior the likelihoods were built with (so the stack reproduces the input posteriors), else Density.flat(). Stacking is exactly one EM step from the interim prior, not the maximum-likelihood population; it is biased toward the interim prior and broadened by the measurement noise, and is provided for comparison only. Its distance from the optimum is PopulationModel(lk).kkt_gap(lk.stack()). With a Basis it is over the components (map it with lk.basis.to_bins), under a flat interim prior unless interim is given.

Parameters:

interimDensity, “flat”, callable, distribution or array_like (K,), optional: Prior the stacked posteriors are formed under; None uses the input’s interim prior.
interim_representation{“mass”, “density”}, optional: Whether an array interim holds masses or densities.

subset(idx)[source]¶

Rows idx (any NumPy index) as a new object.

Parameters:

idxint, slice, array_like of int or bool: Rows to keep.

to_dense()[source]¶: Copy with dense storage.

to_sparse(rtol=0.0)[source]¶

Copy with sparse CSR storage, dropping entries below rtol (relative to row max).

Parameters:

rtolfloat, optional: Entries below this fraction of their row’s maximum are dropped; in [0, 1], and the maximum itself is always kept.

toarray()[source]¶: Dense copy of the row-normalised values.

property values¶: Row-normalised likelihood matrix (dense ndarray or sparse CSR array).

property weights¶: Per-object weights (N,).

with_selection(selection, selection_mode=None)[source]¶

Copy with a (new) selection function attached.

Parameters:

selectionarray_like (K,), callable, Selection or None: Detection probability or exposure per bin; None removes the selection.
selection_mode{“on_measurement”, “on_truth”}, optional: Whether the new selection acts on the measurement or on the truth; required with an array or callable selection.

with_weights(weights, fractional_weights=False)[source]¶

Copy with new object weights.

Parameters:

weightsarray_like (N,): Integer multiplicity of each object.
fractional_weightsbool, optional: Accept non-integer weights, which give a pseudo-likelihood.