scipp.hist#

scipp.hist(x: Union[scipp._scipp.core.Variable, scipp._scipp.core.DataArray], arg_dict: Optional[Dict[str, Union[int, scipp._scipp.core.Variable]]] = None, /, **kwargs: Union[int, scipp._scipp.core.Variable]) → scipp._scipp.core.DataArray#
scipp.hist(x: scipp._scipp.core.Dataset, arg_dict: Optional[Dict[str, Union[int, scipp._scipp.core.Variable]]] = None, /, **kwargs: Union[int, scipp._scipp.core.Variable]) → scipp._scipp.core.Dataset
scipp.hist(x: scipp.core.data_group.DataGroup, arg_dict: Optional[Dict[str, Union[int, scipp._scipp.core.Variable]]] = None, /, **kwargs: Union[int, scipp._scipp.core.Variable]) → scipp.core.data_group.DataGroup

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.

Parameters

  • x – Input data.

  • arg_dict – Dictionary mapping dimension labels to binning parameters.

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

Returns

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}