scipp.bin#

scipp.bin(x, arg_dict=None, /, **kwargs)#

Create binned data by binning input along all dimensions given by edges.

Bin edges can be specified in three ways:

  1. When an integer is provided, a ‘linspace’ with this requested number of bins is created, based on the min and max of the corresponding coordinate.

  2. A scalar Scipp variable (a value with a unit) is interpreted as a target bin width, and an ‘arange’ covering the min and max of the corresponding coordinate is created.

  3. A custom coordinate, given as a Scipp variable with compatible unit. Typically, this should have a single dimension matching the target dimension.

When binning a dimension with an existing dimension-coord, the binning for the dimension is modified, i.e., the input and the output will have the same dimension labels.

When binning by non-dimension-coords, the output will have new dimensions given by the names of these coordinates. These new dimensions replace the dimensions the input coordinates depend on.

Warning

When there is existing binning or grouping, the algorithm assumes that coordinates of the binned data are correct, i.e., compatible with the corresponding coordinate values in the individual bins. If this is not the case then the behavior if UNSPECIFIED. That is, the algorithm may or may not ignore the existing coordinates. If you encounter such as case, remove the conflicting coordinate, e.g., using scipp.DataArray.drop_coords().

Parameters:

  • x – Input data.

  • arg_dict (default: None) – Dictionary mapping dimension labels to binning parameters.

  • **kwargs – Mapping of dimension label to corresponding binning parameters.

Returns:

Binned data.

See also

scipp.hist

For histogramming data.

scipp.group

Creating binned data by grouping, instead of binning based on edges.

scipp.binning.make_binned

Lower level function that can bin and group, and does not automatically replace/erase dimensions.

Examples

Bin a table by one of its coord columns, specifying (1) number of bins, (2) bin width, or (3) actual binning:

>>> from numpy.random import default_rng
>>> rng = default_rng(seed=1234)
>>> x = sc.array(dims=['row'], unit='m', values=rng.random(100))
>>> y = sc.array(dims=['row'], unit='m', values=rng.random(100))
>>> data = sc.ones(dims=['row'], unit='K', shape=[100])
>>> table = sc.DataArray(data=data, coords={'x': x, 'y': y})
>>> table.bin(x=2).sizes
{'x': 2}

>>> table.bin(x=sc.scalar(0.2, unit='m')).sizes
{'x': 5}

>>> table.bin(x=sc.linspace('x', 0.2, 0.8, num=10, unit='m')).sizes
{'x': 9}

Bin a table by two of its coord columns:

>>> table.bin(x=4, y=6).sizes
{'x': 4, 'y': 6}

Bin binned data, using new bins along existing dimension:

>>> binned = table.bin(x=10)
>>> binned.bin(x=20).sizes
{'x': 20}

Bin binned data along an additional dimension:

>>> binned = table.bin(x=10)
>>> binned.bin(y=5).sizes
{'x': 10, 'y': 5}