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.

Parameters
Returns

Union[DataArray, Dataset] – 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}