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

Compute a histogram.

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 histogramming 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 histogramming 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.

  • x – Input data.

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

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


Histogrammed data.

See also


Creating binned data by binning instead of summing all contributions.


Lower level function for histogramming that does not automatically replace/erase dimensions.


Histogram 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.hist(x=2)
Dimensions: Sizes[x:2, ]
* x                         float64              [m]  (x [bin-edge])  [0.00313229, 0.497696, 0.992259]
                            float64              [K]  (x)  [53, 47]
>>> table.hist(x=sc.scalar(0.2, unit='m')).sizes
{'x': 5}
>>> table.hist(x=sc.linspace('x', 0.2, 0.8, num=10, unit='m')).sizes
{'x': 9}

Histogram a table by two of its coord columns:

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

Histogram binned data, using existing bins:

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

Histogram binned data, using new bins along existing dimension:

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

Histogram binned data along an additional dimension:

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