scipp.hist#

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

Compute a histogram.

Bin edges can be specified in three ways:

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

Parameters

x (Union[Variable, DataArray, Dataset]) – Input data.
arg_dict (Optional[Dict[str, Union[int, Variable]]], default: None) – Dictionary mapping dimension labels to binning parameters.
**kwargs – Mapping of dimension label to corresponding binning parameters.

Returns

Union[DataArray, Dataset] – Histogrammed data.

See also

scipp.bin: Creating binned data by binning instead of summing all contributions.
scipp.binning.make_histogrammed: Lower level function for histogramming that does not automatically replace/erase dimensions.

Examples

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)
<scipp.DataArray>
Dimensions: Sizes[x:2, ]
Coordinates:
  x                         float64              [m]  (x [bin-edge])  [0.00313229, 0.497696, 0.992259]
Data:
                            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}