scipp.hist
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:
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 – 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}