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.


Union[DataArray, Dataset] – Binned data.

See also


For histogramming data.

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


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


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}