locan.data.aggregate.Bins#

class locan.data.aggregate.Bins(bins=None, n_bins=None, bin_size=None, bin_edges=None, bin_range=None, labels=None, extend_range=None)[source]#

Bases: object

Bin definitions to be used in histogram and render functions. Bin edges are continuous, contiguous and monotonic. Bins can be instantiated from specifications for bins or bin_edges or for one of n_bins or bin_size in combination with bin_range. One and only one of (bins, bin_edges, n_bins, bin_size) must be different from None in any instantiating function. To pass bin specifications to other functions use an instance of Bins or bin_edges.

Parameters:

  • bins (Bins | boost_histogram.axis.Axis | boost_histogram.axis.AxesTuple | None) – Specific class specifying the bins.

  • bin_edges (Sequence[float] | Sequence[Sequence[float]] | None) – Bin edges for all or each dimension with shape (dimension, n_bin_edges).

  • bin_range (tuple[float, float] | Sequence[float] | Sequence[Sequence[float]]) – Minimum and maximum edge for all or each dimensions with shape (2,) or (dimension, 2).

  • n_bins (int | Sequence[int] | None) – The number of bins for all or each dimension. 5 yields 5 bins in all dimensions. (2, 5) yields 2 bins for one dimension and 5 for the other dimension.

  • bin_size (float | Sequence[float] | Sequence[Sequence[float]] | None) – The size of bins for all or each bin and for all or each dimension with shape (dimension,) or (dimension, n_bins). 5 would describe bin_size of 5 for all bins in all dimensions. ((2, 5),) yield bins of size (2, 5) for one dimension. (2, 5) yields bins of size 2 for one dimension and 5 for the other dimension. ((2, 5), (1, 3)) yields bins of size (2, 5) for one dimension and (1, 3) for the other dimension. To specify arbitrary sequence of bin_size use bin_edges instead.

  • labels (list[str] | None) – Names for each bin axis with shape (dimension,)

  • extend_range (bool | None) –

    If for equally-sized bins the final bin_edge is different from the maximum bin_range, the last bin_edge will be smaller than the maximum bin_range but all bins are equally-sized (None); the last bin_edge will be equal to the maximum bin_range but bins are not equally-sized (False); the last bin_edge will be larger than the maximum bin_range but all bins are equally-sized (True).

    If for variable-sized bins the final bin_edge is different from the maximum bin_range, the last bin_edge will be smaller than the maximum bin_range (None); the last bin_edge will be equal to the maximum bin_range (False); the last bin_edge will be larger than the maximum bin_range but taken from the input sequence (True).

Variables:

  • dimension (int) – The number of dimensions for which bins are provided.

  • bin_range (tuple[tuple[float, float], ...]) – Minimum and maximum edge for each dimension with shape (dimension, 2).

  • bin_edges (tuple[npt.NDArray[np.float64], ...]) – Array(s) with bin edges for each dimension with shape (dimension,)

  • n_bins (tuple[int, ...]) – Number of bins for each dimension with shape (dimension,)

  • bin_size (tuple[float, ...] | tuple[npt.NDArray[np.float64], ...]) – Size of bins for each dimension with shape (dimension,) or with shape (dimension, n_bins).

  • bin_centers (tuple[npt.NDArray[np.float64], ...]) – Array(s) with bin centers for all or each dimension with shape (dimension,).

  • labels (list[str] | None) – Names for each bin axis.

  • boost_histogram_axes (boost_histogram.axis.AxesTuple) – Axis definitions for boost-histogram

Methods

__init__([bins, n_bins, bin_size, ...])

equalize_bin_size()

Return a new instance of Bins with bin_size set equal to the first bin_size element in each dimension and extend_range=None.

Attributes

bin_centers

bin_edges

bin_range

bin_size

boost_histogram_axes

Axis definitions for boost-histogram

dimension

is_equally_sized

True for each dimension if all bins are of the same size.

labels

n_bins

property bin_centers: tuple[ndarray[Any, dtype[float64]], ...]#
property bin_edges: tuple[ndarray[Any, dtype[float64]], ...]#
property bin_range: tuple[tuple[float, float], ...]#
property bin_size: tuple[float, ...] | tuple[ndarray[Any, dtype[float64]], ...]#
property boost_histogram_axes: AxesTuple#

Axis definitions for boost-histogram

property dimension: int#
equalize_bin_size()[source]#

Return a new instance of Bins with bin_size set equal to the first bin_size element in each dimension and extend_range=None.

Return type:

Bins

property is_equally_sized: tuple[bool, ...]#

True for each dimension if all bins are of the same size.

property labels: list[str] | None#
property n_bins: tuple[int, ...]#