Reference / binference.Bins

binference.Bins

class binference.Bins(edges, measure=None, mask=None)

The bins (or categories) over which populations and likelihoods are defined.

A Bins object describes the support of the population distribution: a one-dimensional set of bins, a rectilinear N-dimensional grid of cells (flattened in C order), or a set of unordered categories. It records bin volumes (widths, areas, …), which matter whenever bins have unequal sizes (see The model).

Each grid axis carries a Measure, the coordinate u = T(z) in which the population is flat within a bin (DECISIONS #21): linear by default, logarithmic for log(). A boolean mask over the grid removes cells from the support (DECISIONS #19); the remaining active cells are numbered 0 .. K - 1 in C order.

Parameters:

edgesarray_like

Strictly increasing 1-D bin edges (K + 1 values). Use grid() for N-dimensional grids and categories() for unordered categories.

measureMeasure or {“linear”, “log”}, optional

Coordinate in which the population is flat within a bin. Default linear; hand-built edges that look geometric then raise an InputWarning.

maskarray_like of bool, optional

Which bins are part of the support (default: all).

Examples

>>> import binference
>>> bins = binference.Bins([0.0, 0.5, 1.0, 2.0])
>>> bins.K, bins.volumes.tolist()
(3, [0.5, 0.5, 1.0])
>>> grid = binference.Bins.grid([0, 1, 2], [0, 1, 2, 3])
>>> grid.K, grid.shape
(6, (2, 3))

__init__(edges, measure=None, mask=None)

Methods

__init__(edges[, measure, mask])
categories(labels)	Unordered categories, either K integer labels or explicit labels.
coarsen(factor)	Merge blocks of factor adjacent bins along each axis.
contains(values)	Boolean mask: which values fall inside the support.
flatten(a)	Inverse of unflatten(): the active cells of trailing grid axes.
from_centers(centers[, measure])	1-D bins whose centres in the measure coordinate are centers.
grid(*edges[, measure, mask])	A rectilinear N-dimensional grid of cells from per-axis edges.
grid_index(k)	Per-axis grid indices of the bins k (indices into each axis's edges).
index(values)	Bin index of each value (-1 outside the support or in a masked cell).
linear(lo, hi, n[, mask])	n equal-width bins spanning [lo, hi], linear measure.
log(lo, hi, n[, mask])	n logarithmically spaced bins spanning [lo, hi] (lo > 0), log measure.
neighbors()	Pairs of adjacent active bins, shape (n_pairs, 2) (grids only).
refine(factor)	Split each bin into factor parts of equal width in u along each axis.
sample_within(k, rng)	Values drawn uniformly in u inside the bins k (grids only).
unflatten(a)	Reshape a trailing axis of length K to the grid shape.

Attributes

K	Number of active bins (cells or categories).
cell_index	Per-axis grid indices of every active bin, each (K,).
cells	Flat grid index (C order, masked cells included) of each active bin.
centers	Bin centres in z, the midpoints in u: (K,) in 1-D, (K, ndim) for grids, codes for categories.
edges	Per-axis bin edges (raises for categories).
is_categorical	True for unordered categories.
is_masked	Whether some grid cells are excluded from the support.
labels	Category labels (None for grids).
mask	Boolean array of the grid's shape: which cells are in the support.
measures	Per-axis measures (raises for categories).
ndim	Number of grid dimensions (1 for categories).
ordered	Whether bins have a geometry (grids) as opposed to unordered categories.
range	Per-axis (lo, hi) extent of the grid.
shape	Grid shape, including masked cells ((K,) for categories).
u_edges	Per-axis edges in the measure coordinate u = T(z).
u_volumes	Bin volumes in the measure coordinate u (K,) (raises for categories).
volumes	Bin volumes in z (K,) (widths in 1-D; ones for categories).
widths	Per-axis bin widths in z over the whole grid (raises for categories).

property K

Number of active bins (cells or categories).

classmethod categories(labels)

Unordered categories, either K integer labels or explicit labels.

Parameters:

labelsint or sequence

The number of categories K (labelled 0 to K - 1) or their labels.

property cell_index

Per-axis grid indices of every active bin, each (K,).

property cells

Flat grid index (C order, masked cells included) of each active bin.

property centers

Bin centres in z, the midpoints in u: (K,) in 1-D, (K, ndim) for grids, codes for categories.

coarsen(factor)

Merge blocks of factor adjacent bins along each axis.

Returns the coarse bins (same measures and a coarsened mask) and a (K,) integer map from fine to coarse bins, so that coarse fractions are np.bincount(map, weights=rho). Each block must be wholly active or wholly masked, since a coarse bin’s volume is its full block.

Parameters:

factorint or sequence of int

Bins per block, for all axes or one per axis.

contains(values)

Boolean mask: which values fall inside the support.

Parameters:

valuesarray_like

Values, shaped as for index().

property edges

Per-axis bin edges (raises for categories).

flatten(a)

Inverse of unflatten(): the active cells of trailing grid axes.

Parameters:

aarray_like

Values whose trailing axes have the grid shape.

classmethod from_centers(centers, measure='linear')

1-D bins whose centres in the measure coordinate are centers.

Edges sit at the midpoints of u = T(centers) and the outermost bins extend half a spacing beyond the first and last points, all in u. With measure="log" the edges are geometric midpoints and stay positive. With non-uniform spacing the returned centers (the midpoints of the bins in u) need not equal the input values.

Parameters:

centersarray_like

At least two strictly increasing values.

measureMeasure or {“linear”, “log”}, optional

Coordinate in which the edges sit midway between the centres.

classmethod grid(*edges, measure=None, mask=None)

A rectilinear N-dimensional grid of cells from per-axis edges.

Cells are flattened in C order (the last axis varies fastest); use unflatten() to recover the grid shape. measure is one measure for every axis or a sequence with one per axis; mask has the grid’s shape.

Parameters:

*edgesarray_like

Strictly increasing edges of each axis.

measureMeasure, str or sequence, optional

Coordinate in which the population is flat within a cell, for every axis or one per axis; None is linear.

maskarray_like of bool, optional

Which cells are part of the support, in the grid’s shape (default: all).

grid_index(k)

Per-axis grid indices of the bins k (indices into each axis’s edges).

Parameters:

kint or array_like of int

Bin indices.

index(values)

Bin index of each value (-1 outside the support or in a masked cell).

Bins are left-closed, except the last bin along each axis, which also includes its upper edge. For 1-D bins values has shape (n,) or (n, 1); for N-D grids (n, ndim); for categories it contains labels.

Parameters:

valuesarray_like

Values, or labels for categories.

property is_categorical

True for unordered categories.

property is_masked

Whether some grid cells are excluded from the support.

property labels

Category labels (None for grids).

classmethod linear(lo, hi, n, mask=None)

n equal-width bins spanning [lo, hi], linear measure.

Parameters:

lo, hifloat

Outer edges.

nint

Number of bins.

maskarray_like of bool, optional

Which bins are part of the support (default: all).

classmethod log(lo, hi, n, mask=None)

n logarithmically spaced bins spanning [lo, hi] (lo > 0), log measure.

Parameters:

lo, hifloat

Outer edges.

nint

Number of bins.

maskarray_like of bool, optional

Which bins are part of the support (default: all).

property mask

Boolean array of the grid’s shape: which cells are in the support.

property measures

Per-axis measures (raises for categories).

property ndim

Number of grid dimensions (1 for categories).

neighbors()

Pairs of adjacent active bins, shape (n_pairs, 2) (grids only).

Adjacent means sharing a face (4-neighbour structure in 2-D).

property ordered

Whether bins have a geometry (grids) as opposed to unordered categories.

property range

Per-axis (lo, hi) extent of the grid.

refine(factor)

Split each bin into factor parts of equal width in u along each axis.

Returns the fine bins (same measures, the mask repeated) and the (K_fine,) integer map from fine to coarse bins, as coarsen() returns; fine.coarsen(factor) recovers these bins.

Parameters:

factorint or sequence of int

Parts per bin, for all axes or one per axis.

sample_within(k, rng)

Values drawn uniformly in u inside the bins k (grids only).

Returns an array of k’s shape for 1-D bins, with a trailing axis of length ndim for grids.

Parameters:

kint or array_like of int

Bin indices.

rngnumpy.random.Generator

Random number generator.

property shape

Grid shape, including masked cells ((K,) for categories).

property u_edges

Per-axis edges in the measure coordinate u = T(z).

property u_volumes

Bin volumes in the measure coordinate u (K,) (raises for categories).

unflatten(a)

Reshape a trailing axis of length K to the grid shape.

Masked cells are filled with NaN (the result is then floating point).

Parameters:

aarray_like (…, K)

Values per bin.

property volumes

Bin volumes in z (K,) (widths in 1-D; ones for categories).

property widths

Per-axis bin widths in z over the whole grid (raises for categories).