scipp.fold

scipp.fold(x, dim, *, dims=None, shape=None, sizes=None)

Fold a single dimension of a variable or data array into multiple dims.

One and only one of these sets of arguments must be given:

• dims and shape

• sizes

Parameters:

• x (scipp.typing.VariableLike) – Variable or DataArray to fold.

• dim (str) – A single dim label that will be folded into more dims.

• sizes (Optional[dict[str, int]], default: None) – A dict mapping new dims to new shapes.

• dims (Optional[Sequence[str]], default: None) – A list of new dims labels.

• shape (Optional[Sequence[int]], default: None) – A list of new dim shapes.

Returns:

Same type as input – Variable or DataArray with requested dimension labels and shape.

Raises:

scipp.DimensionError – If the volume of the old shape is not equal to the volume of the new shape.

Examples

>>> v = sc.arange('x', 6)
>>> v
<scipp.Variable> (x: 6)      int64  [dimensionless]  [0, 1, ..., 4, 5]
>>> sc.fold(v, dim='x', sizes={'y': 2, 'z': 3})
<scipp.Variable> (y: 2, z: 3)      int64  [dimensionless]  [0, 1, ..., 4, 5]
>>> sc.fold(v, dim='x', sizes={'y': 2, 'z': 3}).values
array([[0, 1, 2],
       [3, 4, 5]])

>>> sc.fold(v, dim='x', dims=['y', 'z'], shape=[2, 3])
<scipp.Variable> (y: 2, z: 3)      int64  [dimensionless]  [0, 1, ..., 4, 5]

>>> sc.fold(v, dim='x', sizes={'y': 2, 'z': -1})
<scipp.Variable> (y: 2, z: 3)      int64  [dimensionless]  [0, 1, ..., 4, 5]

>>> a = sc.DataArray(0.1 * sc.arange('x', 6), coords={'x': sc.arange('x', 6)})
>>> sc.fold(a, dim='x', sizes={'y': 2, 'z': 3})
<scipp.DataArray>
Dimensions: Sizes[y:2, z:3, ]
Coordinates:
* x                           int64  [dimensionless]  (y, z)  [0, 1, ..., 4, 5]
Data:
                            float64  [dimensionless]  (y, z)  [0, 0.1, ..., 0.4, 0.5]
>>> sc.fold(a, dim='x', sizes={'y': 2, 'z': 3}).data.values
array([[0. , 0.1, 0.2],
       [0.3, 0.4, 0.5]])
>>> sc.fold(a, dim='x', sizes={'y': 2, 'z': 3}).coords['x'].values
array([[0, 1, 2],
       [3, 4, 5]])