scipp.bins#

scipp.bins(*, data, dim, begin=None, end=None, validate_indices=True)#

Create a binned variable from bin indices.

The elements of the returned variable are “bins”, defined as views into data. The returned variable keeps and manages a copy of data internally.

The variables begin and end must have the same dims and shape and dtype=sc.DType.int64. The output dims and shape are given by begin. If only begin is given, each bucket is a slice containing a non-range slice of data at the given indices. If neither begin nor end are given, the output has dims=[dim] and contains all non-range slices along that dimension.

Parameters:
  • begin (Optional[Variable], default: None) – Optional begin indices of bins, used for slicing data. If not provided each row of data is mapped to a different bin.

  • end (Optional[Variable], default: None) – Optional end indices of bins, used for slicing data. If not provided, begin is used as starting offsets for each bin, i.e., the end of the Nth bin is set to the begin of the N+1st bin.

  • dim (str) – Dimension of data that will be sliced to obtain data for any given bin.

  • data (VariableLike) – A variable, data array, or dataset containing combined data of all bins.

  • validate_indices (bool, default: True) – If True (default), validates that all indices are within bounds of the data and that bins are not overlapping. If False, skips validation for better performance but may cause undefined behavior if indices are out of bounds or overlapping. USE WITH EXTREME CAUTION and only if you know what you are doing! An example of safe usage of this option is reconstruction of binned data from the result of a obj.bins.constituents call.

Returns:

Variable – Variable containing data in bins.

See also

scipp.bin

For creating DataArrays based on binning of coord value instead of explicitly given index ranges.