scipp.flatten#

scipp.flatten(x, dims=None, to=None)#

Flatten multiple dimensions into a single dimension.

If the input has a bin-edge coordinate that cannot be joined together it will not be included in the output.

If the input is a DataArray then coords, masks, and attrs that contain at least one of the flattened dimensions will also be flattened. This implies that when flattening all dims, i.e., when dims=None, all coords, masks, and attrs that share some or all dimensions with the data will be flattened.

Parameters:

  • x (scipp.typing.VariableLike) – Multi-dimensional input to flatten.

  • dims (Optional[Sequence[str]], default: None) – A list of dim labels that will be flattened. If None, all dimensions will be flattened. If the list is empty, this will effectively add a new inner dimension of length 1 to the data (meta data such as coords and masks are not touched in this case).

  • to (Optional[str], default: None) – A single dim label for the resulting flattened dim.

Returns:

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

Raises:

scipp.DimensionError – If the input does not have a contiguous memory layout, i.e. flattening would require moving data around. This can be resolved by (deep-)copying the input.

Examples

>>> v = sc.array(dims=['x', 'y'], values=np.arange(6).reshape(2, 3))
>>> v
<scipp.Variable> (x: 2, y: 3)      int64  [dimensionless]  [0, 1, ..., 4, 5]
>>> sc.flatten(v, to='u')
<scipp.Variable> (u: 6)      int64  [dimensionless]  [0, 1, ..., 4, 5]
>>> sc.flatten(v, dims=['x', 'y'], to='u')
<scipp.Variable> (u: 6)      int64  [dimensionless]  [0, 1, ..., 4, 5]

>>> v = sc.array(dims=['x', 'y', 'z'], values=np.arange(24).reshape(2, 3, 4))
>>> v
<scipp.Variable> (x: 2, y: 3, z: 4)      int64  [dimensionless]  [0, 1, ..., 22, 23]
>>> sc.flatten(v, to='u')
<scipp.Variable> (u: 24)      int64  [dimensionless]  [0, 1, ..., 22, 23]
>>> sc.flatten(v, dims=['x', 'y'], to='u')
<scipp.Variable> (u: 6, z: 4)      int64  [dimensionless]  [0, 1, ..., 22, 23]
>>> sc.flatten(v, dims=['y', 'z'], to='u')
<scipp.Variable> (x: 2, u: 12)      int64  [dimensionless]  [0, 1, ..., 22, 23]

>>> a = sc.DataArray(0.1 * sc.array(dims=['x', 'y'], values=np.arange(6).reshape(2, 3)),
...        coords={'x': sc.arange('x', 2),
...                'y': sc.arange('y', 3),
...                'xy': sc.array(dims=['x', 'y'],
...                               values=np.arange(6).reshape(2, 3))})
>>> a
<scipp.DataArray>
Dimensions: Sizes[x:2, y:3, ]
Coordinates:
* x                           int64  [dimensionless]  (x)  [0, 1]
* xy                          int64  [dimensionless]  (x, y)  [0, 1, ..., 4, 5]
* y                           int64  [dimensionless]  (y)  [0, 1, 2]
Data:
                            float64  [dimensionless]  (x, y)  [0, 0.1, ..., 0.4, 0.5]
>>> sc.flatten(a, to='u')
<scipp.DataArray>
Dimensions: Sizes[u:6, ]
Coordinates:
* x                           int64  [dimensionless]  (u)  [0, 0, ..., 1, 1]
* xy                          int64  [dimensionless]  (u)  [0, 1, ..., 4, 5]
* y                           int64  [dimensionless]  (u)  [0, 1, ..., 1, 2]
Data:
                            float64  [dimensionless]  (u)  [0, 0.1, ..., 0.4, 0.5]