scipp.DataArray#

class scipp.DataArray#

Named variable with associated coords and masks.

DataArrays support rich indexing with dimension labels and coordinate values:

Examples

Create a data array and access elements:

>>> import scipp as sc
>>> da = sc.DataArray(
...     sc.array(dims=['x'], values=[1.0, 2.0, 3.0, 4.0], unit='K'),
...     coords={'x': sc.array(dims=['x'], values=[0.0, 1.0, 2.0, 3.0], unit='m')},
... )

Integer indexing with explicit dimension:

>>> da['x', 0]
<scipp.DataArray>
Dimensions: Sizes[]
Coordinates:
  x                         float64              [m]  ()  0
Data:
                            float64              [K]  ()  1

Slicing preserves coordinates:

>>> da['x', 1:3]
<scipp.DataArray>
Dimensions: Sizes[x:2, ]
Coordinates:
* x                         float64              [m]  (x)  [1, 2]
Data:
                            float64              [K]  (x)  [2, 3]

Label-based indexing with a scalar value:

>>> da['x', sc.scalar(1.0, unit='m')]
<scipp.DataArray>
Dimensions: Sizes[]
Coordinates:
  x                         float64              [m]  ()  1
Data:
                            float64              [K]  ()  2

Label-based slicing with a range:

>>> da['x', sc.scalar(0.5, unit='m'):sc.scalar(2.5, unit='m')]
<scipp.DataArray>
Dimensions: Sizes[x:2, ]
Coordinates:
* x                         float64              [m]  (x)  [1, 2]
Data:
                            float64              [K]  (x)  [2, 3]

Boolean masking:

>>> condition = da.coords['x'] > sc.scalar(1.0, unit='m')
>>> da[condition]
<scipp.DataArray>
Dimensions: Sizes[x:2, ]
Coordinates:
* x                         float64              [m]  (x)  [2, 3]
Data:
                            float64              [K]  (x)  [3, 4]

See also

scipp.Variable, scipp.Dataset

__init__(self, data: Variable, coords: Mapping[str, Variable] | Iterable[tuple[str, Variable]] = {}, masks: Mapping[str, Variable] | Iterable[tuple[str, Variable]] = {}, name: str = '') → None#

DataArray initializer.

Parameters:

data – Data and optionally variances.
coords – Coordinates referenced by dimension.
masks – Masks referenced by name.
name – Name of the data array.

Examples

Create a DataArray with data and a coordinate:

>>> import scipp as sc
>>> da = sc.DataArray(
...     data=sc.array(dims=['x'], values=[1.0, 2.0, 3.0], unit='K'),
...     coords={'x': sc.array(dims=['x'], values=[0.1, 0.2, 0.3], unit='m')},
... )
>>> da.dims, da.shape
(('x',), (3,))
>>> da.unit == sc.Unit('K')
True

Methods

`__init__`(self, data[, coords, masks, name])	DataArray initializer.
`all`([dim])	Logical AND over input values.
`any`([dim])	Logical OR over input values.
`assign`(data)	Return new data array with updated data.
`assign_coords`([coords])	Return new object with updated or inserted coordinate.
`assign_masks`([masks])	Return new object with updated or inserted masks.
`astype`(self, type, *[, copy])	Converts a Variable or DataArray to a different dtype.
`bin`([arg_dict, dim])	Create binned data by binning input along all dimensions given by edges.
`broadcast`(*[, dims, shape, sizes])	Broadcast a Variable or a DataArray.
`ceil`(*[, out])	Round up to the nearest integer of all values passed in x.
`copy`(self[, deep])	Return a (by default deep) copy.
`drop_coords`(args, *kwargs)	Overloaded function.
`drop_masks`(args, *kwargs)	Overloaded function.
`flatten`([dims, to])	Flatten multiple dimensions into a single dimension.
`floor`(*[, out])	Round down to the nearest integer of all values passed in x.
`fold`(dim, *[, dims, shape, sizes])	Fold a single dimension of a variable or data array into multiple dims.
`group`(*args[, dim])	Create binned data by grouping input by one or more coordinates.
`groupby`(group, *[, bins])	Group dataset or data array based on values of specified labels.
`hist`([arg_dict, dim])	Compute a histogram.
`max`([dim])	Maximum of elements in the input.
`mean`([dim])	Arithmetic mean of elements in the input.
`median`([dim])	Compute the median of the input values.
`min`([dim])	Minimum of elements in the input.
`nanhist`([arg_dict, dim])	Compute a histogram, skipping NaN values.
`nanmax`([dim])	Maximum of elements in the input ignoring NaN's.
`nanmean`([dim])	Arithmetic mean of elements in the input ignoring NaN's.
`nanmedian`([dim])	Compute the median of the input values ignoring NaN's.
`nanmin`([dim])	Minimum of elements in the input ignoring NaN's.
`nanstd`([dim])	Compute the standard deviation of the input values ignoring NaN's.
`nansum`([dim])	Sum of elements in the input ignoring NaN's.
`nanvar`([dim])	Compute the variance of the input values ignoring NaN's.
`plot`(**kwargs)	Wrapper function to plot data.
`rebin`([arg_dict])	Rebin a data array or dataset.
`rename`([dims_dict])	Rename the dimensions, coordinates, and attributes.
`rename_dims`([dims_dict])	Rename dimensions.
`round`(*[, decimals, out])	Round to the given number of decimals.
`save_hdf5`(filename)	Write an object out to file in HDF5 format.
`squeeze`([dim])	Remove dimensions of length 1.
`std`([dim])	Compute the standard deviation of the input values.
`sum`([dim])	Sum of elements in the input.
`to`(*[, unit, dtype, copy])	Converts a Variable or DataArray to a different dtype and/or a different unit.
`transform_coords`([targets, graph, ...])	Compute new coords based on transformations of input coords.
`transpose`([dims])	Transpose dimensions of the input.
`underlying_size`(self)	Return the size of the object in bytes.
`var`([dim])	Compute the variance of the input values.

Attributes

`bins`	Returns helper `scipp.Bins` for bin-wise operations.
`coords`	Dict of coordinates.
`data`	Underlying data Variable.
`dim`	The only dimension label for 1-dimensional data, raising an exception if the data is not 1-dimensional.
`dims`	Dimension labels of the data (read-only).
`dtype`	Data type contained in the variable.
`is_binned`	Return True if the object is binned.
`masks`	Dict of masks.
`name`	The name of the held data.
`ndim`	Number of dimensions of the data (read-only).
`shape`	Shape of the data (read-only).
`size`	Number of elements in the data (read-only).
`sizes`	dict mapping dimension labels to dimension sizes (read-only).
`unit`	Physical unit of the data.
`value`	The only value for 0-dimensional data, raising an exception if the data is not 0-dimensional.
`values`	Array of values of the data.
`variance`	The only variance for 0-dimensional data, raising an exception if the data is not 0-dimensional.
`variances`	Array of variances of the data.

__getitem__(*args, **kwargs)#

Overloaded function.

__getitem__(self: scipp._scipp.core.DataArray, arg0: typing.SupportsInt) -> scipp._scipp.core.DataArray
__getitem__(self: scipp._scipp.core.DataArray, arg0: slice) -> scipp._scipp.core.DataArray
__getitem__(self: scipp._scipp.core.DataArray, arg0: scipp._scipp.core.Variable) -> scipp._scipp.core.DataArray
__getitem__(self: scipp._scipp.core.DataArray, arg0: tuple[str, scipp._scipp.core.Variable]) -> scipp._scipp.core.DataArray
__getitem__(self: scipp._scipp.core.DataArray, arg0: tuple[str, typing.SupportsInt]) -> scipp._scipp.core.DataArray
__getitem__(self: scipp._scipp.core.DataArray, arg0: tuple[str, slice]) -> scipp._scipp.core.DataArray
__getitem__(self: scipp._scipp.core.DataArray, arg0: ellipsis) -> scipp._scipp.core.DataArray
__getitem__(self: scipp._scipp.core.DataArray, arg0: collections.abc.Sequence[typing.SupportsInt]) -> scipp._scipp.core.DataArray
__getitem__(self: scipp._scipp.core.DataArray, arg0: tuple[str, collections.abc.Sequence[typing.SupportsInt]]) -> scipp._scipp.core.DataArray

all(dim=None)#

Logical AND over input values.

Seealso:: Details in scipp.all()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

any(dim=None)#

Logical OR over input values.

Seealso:: Details in scipp.any()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

assign(data)#

Return new data array with updated data.

Parameters:: data (Variable) – New data.
Returns:: DataArray – scipp.DataArray with updated data.

Examples

Replace the data in a DataArray while preserving coordinates:

>>> import scipp as sc
>>> da = sc.DataArray(
...     sc.array(dims=['x'], values=[1.0, 2.0, 3.0]),
...     coords={'x': sc.arange('x', 3)}
... )
>>> new_data = sc.array(dims=['x'], values=[10.0, 20.0, 30.0], unit='m')
>>> da.assign(new_data)
<scipp.DataArray>
Dimensions: Sizes[x:3, ]
Coordinates:
* x                           int64  [dimensionless]  (x)  [0, 1, 2]
Data:
                            float64              [m]  (x)  [10, 20, 30]

assign_coords(coords=None, /, **coords_kwargs)#

Return new object with updated or inserted coordinate.

Parameters:

coords (Mapping[str, Variable] | Iterable[tuple[str, Variable]] | None, default: None) – New coordinates.
coords_kwargs (Variable) – Keyword arguments form of coords.

Returns:

TypeVar(_T, Dataset, DataArray) – scipp.DataArray or scipp.Dataset with updated coordinates.

Examples

Add a new coordinate using keyword arguments:

>>> import scipp as sc
>>> da = sc.DataArray(
...     sc.array(dims=['x'], values=[1.0, 2.0, 3.0]),
...     coords={'x': sc.arange('x', 3)}
... )
>>> da.assign_coords(y=sc.array(dims=['x'], values=[10, 20, 30]))
<scipp.DataArray>
Dimensions: Sizes[x:3, ]
Coordinates:
* x                           int64  [dimensionless]  (x)  [0, 1, 2]
* y                           int64  [dimensionless]  (x)  [10, 20, 30]
Data:
                            float64  [dimensionless]  (x)  [1, 2, 3]

Update an existing coordinate using a dict:

>>> da.assign_coords({'x': sc.arange('x', 3.0, unit='m')})
<scipp.DataArray>
Dimensions: Sizes[x:3, ]
Coordinates:
* x                         float64              [m]  (x)  [0, 1, 2]
Data:
                            float64  [dimensionless]  (x)  [1, 2, 3]

assign_masks(masks=None, /, **masks_kwargs)#

Return new object with updated or inserted masks.

Parameters:

masks (Mapping[str, Variable] | Iterable[tuple[str, Variable]] | None, default: None) – New masks.
masks_kwargs (Variable) – Keyword arguments form of masks.

Returns:

DataArray – scipp.DataArray with updated masks.

Examples

Add a new mask using keyword arguments:

>>> import scipp as sc
>>> da = sc.DataArray(
...     sc.array(dims=['x'], values=[1.0, 2.0, 3.0]),
...     coords={'x': sc.arange('x', 3)}
... )
>>> da.assign_masks(mask=sc.array(dims=['x'], values=[False, True, False]))
<scipp.DataArray>
Dimensions: Sizes[x:3, ]
Coordinates:
* x                           int64  [dimensionless]  (x)  [0, 1, 2]
Data:
                            float64  [dimensionless]  (x)  [1, 2, 3]
Masks:
  mask                         bool        <no unit>  (x)  [False, True, False]

Add multiple masks using a dict:

>>> da.assign_masks({
...     'low': da.data < sc.scalar(2.0),
...     'high': da.data > sc.scalar(2.0),
... })
<scipp.DataArray>
Dimensions: Sizes[x:3, ]
Coordinates:
* x                           int64  [dimensionless]  (x)  [0, 1, 2]
Data:
                            float64  [dimensionless]  (x)  [1, 2, 3]
Masks:
  high                         bool        <no unit>  (x)  [False, False, True]
  low                          bool        <no unit>  (x)  [True, False, False]

astype(self: scipp._scipp.core.DataArray, type: object, *, copy: bool = True) → scipp._scipp.core.DataArray#

Converts a Variable or DataArray to a different dtype.

If the dtype is unchanged and copy is False, the object is returned without making a deep copy.

Parameters:

type – Target dtype.
copy – If False, return the input object if possible. If True, the function always returns a new object.

Raises:

If the data cannot be converted to the requested dtype.

Returns:

New variable or data array with specified dtype.

Return type:

Union[scipp.Variable, scipp.DataArray]

Examples

Convert integers to floating-point:

>>> import scipp as sc
>>> var = sc.array(dims=['x'], values=[1, 2, 3])
>>> var.dtype
DType('int64')
>>> var.astype('float64')
<scipp.Variable> (x: 3)    float64  [dimensionless]  [1, 2, 3]

Convert floats to integers (truncates toward zero):

>>> sc.array(dims=['x'], values=[1.7, 2.3, -0.8]).astype('int64')
<scipp.Variable> (x: 3)      int64  [dimensionless]  [1, 2, 0]

With copy=False, avoid unnecessary copies when dtype is unchanged:

>>> var_f64 = sc.array(dims=['x'], values=[1.0, 2.0], dtype='float64')
>>> var_f64.astype('float64', copy=False).dtype
DType('float64')

bin(arg_dict=None, /, *, dim=None, **kwargs)#

Create binned data by binning input along all dimensions given by edges.

Seealso:: Details in scipp.bin()
Return type:: DataArray | DataGroup[Any]

property bins: Bins[_O]#: Returns helper scipp.Bins for bin-wise operations.

Deprecated since version 25.11.0: bins currently returns None if the object is not binned. In the future, this will change and bins will raise a scipp.BinnedDataError instead. Use x.is_binned instead of x.bins is not None to check if x contains binned data.

broadcast(*, dims=None, shape=None, sizes=None)#

Broadcast a Variable or a DataArray.

Seealso:: Details in scipp.broadcast()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

ceil(*, out=None)#

Round up to the nearest integer of all values passed in x.

Seealso:: Details in scipp.ceil()
Return type:: TypeVar(_T)

property coords#

Dict of coordinates.

Coordinates define the axis labels for each dimension. They can be point-coordinates (one value per data point) or bin-edge coordinates (one more value than data points).

Examples

>>> import scipp as sc
>>> da = sc.DataArray(
...     sc.array(dims=['x', 'y'], values=[[1, 2], [3, 4]]),
...     coords={
...         'x': sc.array(dims=['x'], values=[0.0, 1.0], unit='m'),
...         'y': sc.array(dims=['y'], values=[10.0, 20.0], unit='s')
...     }
... )
>>> da.coords
<scipp.Dict>
  x: <scipp.Variable> (x: 2)    float64              [m]  [0, 1]
  y: <scipp.Variable> (y: 2)    float64              [s]  [10, 20]

Access individual coordinates:

>>> da.coords['x']
<scipp.Variable> (x: 2)    float64              [m]  [0, 1]

List coordinate names:

>>> da.coords.keys()
<scipp.Dict.keys {x, y}>

copy(self: scipp._scipp.core.DataArray, deep: bool = True) → scipp._scipp.core.DataArray#

Return a (by default deep) copy.

If deep=True (the default), a deep copy is made. Otherwise, a shallow copy is made, and the returned data (and meta data) values are new views of the data and meta data values of this object.

Examples

>>> import scipp as sc
>>> var = sc.array(dims=['x'], values=[1.0, 2.0, 3.0], unit='m')
>>> var_copy = var.copy()
>>> var_copy.values[0] = 999.0
>>> var  # Original unchanged
<scipp.Variable> (x: 3)    float64              [m]  [1, 2, 3]

property data#

Underlying data Variable.

The data property provides access to the data values of a DataArray as a Variable, without the coordinates and masks.

Examples

>>> import scipp as sc
>>> da = sc.DataArray(
...     sc.array(dims=['x'], values=[1.0, 2.0, 3.0], unit='m'),
...     coords={'x': sc.arange('x', 3, unit='s')}
... )
>>> da.data
<scipp.Variable> (x: 3)    float64              [m]  [1, 2, 3]

The data can be replaced entirely:

>>> da.data = sc.array(dims=['x'], values=[10.0, 20.0, 30.0], unit='m')
>>> da.data
<scipp.Variable> (x: 3)    float64              [m]  [10, 20, 30]

property dim#

The only dimension label for 1-dimensional data, raising an exception if the data is not 1-dimensional.

Examples

>>> import scipp as sc
>>> var = sc.array(dims=['x'], values=[1, 2, 3], unit='m')
>>> var.dim
'x'

>>> da = sc.DataArray(sc.array(dims=['time'], values=[1.0, 2.0, 3.0], unit='K'))
>>> da.dim
'time'

property dims#

Dimension labels of the data (read-only).

Examples

>>> import scipp as sc
>>> var = sc.array(dims=['x', 'y'], values=[[1, 2], [3, 4]])
>>> var.dims
('x', 'y')

>>> da = sc.DataArray(
...     sc.array(dims=['x', 'y'], values=[[1.0, 2.0], [3.0, 4.0]]),
...     coords={'x': sc.array(dims=['x'], values=[0.0, 1.0], unit='m')}
... )
>>> da.dims
('x', 'y')

drop_coords(*args, **kwargs)#

Overloaded function.

drop_coords(self: scipp._scipp.core.DataArray, coord_names: str) -> scipp._scipp.core.DataArray

Return new object with specified coordinate(s) removed.

Parameters:: coord_names – Name of the coordinate to remove, or a list of names.
Returns:: New DataArray without the specified coordinate(s).

Examples

Remove a single coordinate:

>>> import scipp as sc
>>> da = sc.DataArray(
...     sc.array(dims=['x'], values=[1.0, 2.0, 3.0]),
...     coords={
...         'x': sc.arange('x', 3),
...         'y': sc.array(dims=['x'], values=[10, 20, 30])
...     }
... )
>>> da.drop_coords('y')
<scipp.DataArray>
Dimensions: Sizes[x:3, ]
Coordinates:
* x                           int64  [dimensionless]  (x)  [0, 1, 2]
Data:
                            float64  [dimensionless]  (x)  [1, 2, 3]

Remove multiple coordinates:

>>> da.coords['z'] = sc.array(dims=['x'], values=[100, 200, 300])
>>> da.drop_coords(['y', 'z'])
<scipp.DataArray>
Dimensions: Sizes[x:3, ]
Coordinates:
* x                           int64  [dimensionless]  (x)  [0, 1, 2]
Data:
                            float64  [dimensionless]  (x)  [1, 2, 3]

drop_coords(self: scipp._scipp.core.DataArray, coord_names: collections.abc.Sequence[str]) -> scipp._scipp.core.DataArray

drop_masks(*args, **kwargs)#

Overloaded function.

drop_masks(self: scipp._scipp.core.DataArray, mask_names: str) -> scipp._scipp.core.DataArray

Return new object with specified mask(s) removed.

Parameters:: mask_names – Name of the mask to remove, or a list of names.
Returns:: New DataArray without the specified mask(s).

Examples

Remove a single mask:

>>> import scipp as sc
>>> da = sc.DataArray(
...     sc.array(dims=['x'], values=[1.0, 2.0, 3.0]),
...     coords={'x': sc.arange('x', 3)},
...     masks={
...         'm1': sc.array(dims=['x'], values=[False, True, False]),
...         'm2': sc.array(dims=['x'], values=[True, False, False])
...     }
... )
>>> da.drop_masks('m1')
<scipp.DataArray>
Dimensions: Sizes[x:3, ]
Coordinates:
* x                           int64  [dimensionless]  (x)  [0, 1, 2]
Data:
                            float64  [dimensionless]  (x)  [1, 2, 3]
Masks:
  m2                           bool        <no unit>  (x)  [True, False, False]

Remove multiple masks:

>>> da.drop_masks(['m1', 'm2'])
<scipp.DataArray>
Dimensions: Sizes[x:3, ]
Coordinates:
* x                           int64  [dimensionless]  (x)  [0, 1, 2]
Data:
                            float64  [dimensionless]  (x)  [1, 2, 3]

drop_masks(self: scipp._scipp.core.DataArray, mask_names: collections.abc.Sequence[str]) -> scipp._scipp.core.DataArray

property dtype#

Data type contained in the variable.

Examples

>>> import scipp as sc
>>> sc.array(dims=['x'], values=[1, 2, 3]).dtype
DType('int64')
>>> sc.array(dims=['x'], values=[1.0, 2.0, 3.0]).dtype
DType('float64')
>>> sc.array(dims=['x'], values=['a', 'b', 'c']).dtype
DType('string')

flatten(dims=None, to=None)#

Flatten multiple dimensions into a single dimension.

Seealso:: Details in scipp.flatten()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

floor(*, out=None)#

Round down to the nearest integer of all values passed in x.

Seealso:: Details in scipp.floor()
Return type:: TypeVar(_T)

fold(dim, *, dims=None, shape=None, sizes=None)#

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

Seealso:: Details in scipp.fold()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

group(*args, dim=None)#

Create binned data by grouping input by one or more coordinates.

Seealso:: Details in scipp.group()
Return type:: DataArray | DataGroup[Any]

groupby(group, *, bins=None)#

Group dataset or data array based on values of specified labels.

Seealso:: Details in scipp.groupby()
Return type:: GroupByDataArray | GroupByDataset

hist(arg_dict=None, /, *, dim=None, **kwargs)#

Compute a histogram.

Seealso:: Details in scipp.hist()
Return type:: Variable | DataArray | Dataset | DataGroup[Any]

property is_binned: bool#: Return True if the object is binned.

property masks#

Dict of masks.

Masks are boolean Variables that mark data points as valid (False) or invalid (True). Masked data is excluded from most operations.

Examples

>>> import scipp as sc
>>> da = sc.DataArray(sc.array(dims=['x'], values=[1.0, 2.0, 3.0, 4.0]))
>>> da.masks['outliers'] = sc.array(dims=['x'], values=[False, False, True, False])
>>> da.masks
<scipp.Dict>
  outliers: <scipp.Variable> (x: 4)       bool        <no unit>  [False, False, True, False]

Check if a mask exists:

>>> 'outliers' in da.masks
True

Access a mask:

>>> da.masks['outliers']
<scipp.Variable> (x: 4)       bool        <no unit>  [False, False, True, False]

Masked values are excluded from reductions:

>>> float(da.sum().value)  # third element (3.0) is masked out
7.0

max(dim=None)#

Maximum of elements in the input.

Seealso:: Details in scipp.max()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

mean(dim=None)#

Arithmetic mean of elements in the input.

Seealso:: Details in scipp.mean()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

median(dim=None)#

Compute the median of the input values.

Seealso:: Details in scipp.median()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

min(dim=None)#

Minimum of elements in the input.

Seealso:: Details in scipp.min()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

property name#

The name of the held data.

Examples

>>> import scipp as sc
>>> da = sc.DataArray(sc.array(dims=['x'], values=[1.0, 2.0, 3.0]))
>>> da.name
''
>>> da.name = 'temperature'
>>> da.name
'temperature'

The name is preserved through operations:

>>> summed = da.sum()
>>> summed.name
'temperature'

nanhist(arg_dict=None, /, *, dim=None, **kwargs)#

Compute a histogram, skipping NaN values.

Seealso:: Details in scipp.nanhist()
Return type:: Variable | DataArray | Dataset | DataGroup[Any]

nanmax(dim=None)#

Maximum of elements in the input ignoring NaN’s.

Seealso:: Details in scipp.nanmax()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

nanmean(dim=None)#

Arithmetic mean of elements in the input ignoring NaN’s.

Seealso:: Details in scipp.nanmean()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

nanmedian(dim=None)#

Compute the median of the input values ignoring NaN’s.

Seealso:: Details in scipp.nanmedian()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

nanmin(dim=None)#

Minimum of elements in the input ignoring NaN’s.

Seealso:: Details in scipp.nanmin()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

nanstd(dim=None, *, ddof)#

Compute the standard deviation of the input values ignoring NaN’s.

Seealso:: Details in scipp.nanstd()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

nansum(dim=None)#

Sum of elements in the input ignoring NaN’s.

Seealso:: Details in scipp.nansum()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

nanvar(dim=None, *, ddof)#

Compute the variance of the input values ignoring NaN’s.

Seealso:: Details in scipp.nanvar()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

property ndim#

Number of dimensions of the data (read-only).

Examples

>>> import scipp as sc
>>> sc.scalar(1.0).ndim
0

>>> sc.array(dims=['x'], values=[1, 2, 3]).ndim
1

>>> sc.array(dims=['x', 'y'], values=[[1, 2], [3, 4]]).ndim
2

plot(**kwargs)#

Wrapper function to plot data. See https://scipp.github.io/plopp/ for details.

Return type:: Any

rebin(arg_dict=None, /, **kwargs)#

Rebin a data array or dataset.

Seealso:: Details in scipp.rebin()
Return type:: Variable | DataArray | Dataset | DataGroup[Any]

rename(dims_dict=None, /, **names)#

Rename the dimensions, coordinates, and attributes.

The renaming can be defined:

using a dict mapping the old to new names, e.g. rename({'x': 'a', 'y': 'b'})
using keyword arguments, e.g. rename(x='a', y='b')

In both cases, x is renamed to a and y to b.

Names not specified in either input are unchanged.

Parameters:

dims_dict (Mapping[str, str] | Iterable[tuple[str, str]] | None, default: None) – Dictionary or items iterator mapping old to new names.
names (str) – Mapping of old to new names as keyword arguments.

Returns:

DataArray – A new data array with renamed dimensions, coordinates, and attributes. Buffers are shared with the input.

See also

scipp.DataArray.rename_dims: Only rename dimensions, not coordinates and attributes.

rename_dims(dims_dict=None, /, **names)#

Rename dimensions.

The renaming can be defined:

using a dict mapping the old to new names, e.g. rename_dims({'x': 'a', 'y': 'b'})
using keyword arguments, e.g. rename_dims(x='a', y='b')

In both cases, x is renamed to a and y to b.

Dimensions not specified in either input are unchanged.

This function only renames dimensions. See the rename method to also rename coordinates and attributes.

Parameters:

dims_dict (Mapping[str, str] | Iterable[tuple[str, str]] | None, default: None) – Dictionary or items iterator mapping old to new names.
names (str) – Mapping of old to new names as keyword arguments.

Returns:

TypeVar(_T, Variable, DataArray, Dataset) – A new object with renamed dimensions.

Examples

>>> import scipp as sc
>>> var = sc.array(dims=['x', 'y'], values=[[1, 2], [3, 4]])
>>> var.rename_dims({'x': 'row', 'y': 'col'}).sizes
{'row': 2, 'col': 2}

Using keyword arguments:

>>> var.rename_dims(x='a', y='b').dims
('a', 'b')

Only specified dimensions are renamed:

>>> var.rename_dims(x='i').dims
('i', 'y')

round(*, decimals=0, out=None)#

Round to the given number of decimals.

Seealso:: Details in scipp.round()
Return type:: TypeVar(_T)

save_hdf5(filename)#

Write an object out to file in HDF5 format.

Supported types include Variable, DataArray, Dataset, and DataGroup. Nested structures are supported.

Parameters:

obj (object) – The object to save. Can be a Variable, DataArray, Dataset, or DataGroup.
filename (str | PathLike[str] | StringIO | BytesIO | Group) – Path to the output file or an open HDF5 group.

Return type:

None

See also

scipp.io.load_hdf5: Load data from HDF5 files.

Examples

Save and load a Variable:

>>> import scipp as sc
>>> import tempfile
>>> var = sc.array(dims=['x'], values=[1.0, 2.0, 3.0], unit='m')
>>> with tempfile.NamedTemporaryFile(suffix='.h5') as f:
...     sc.io.save_hdf5(var, f.name)
...     loaded = sc.io.load_hdf5(f.name)
>>> loaded
<scipp.Variable> (x: 3)    float64              [m]  [1, 2, 3]

Save and load a DataArray with coordinates:

>>> da = sc.DataArray(
...     sc.array(dims=['x'], values=[10, 20, 30], unit='counts'),
...     coords={'x': sc.array(dims=['x'], values=[0.1, 0.2, 0.3], unit='m')}
... )
>>> with tempfile.NamedTemporaryFile(suffix='.h5') as f:
...     sc.io.save_hdf5(da, f.name)
...     loaded = sc.io.load_hdf5(f.name)
>>> loaded
<scipp.DataArray>
Dimensions: Sizes[x:3, ]
Coordinates:
* x                         float64              [m]  (x)  [0.1, 0.2, 0.3]
Data:
                              int64         [counts]  (x)  [10, 20, 30]

property shape#

Shape of the data (read-only).

Examples

>>> import scipp as sc
>>> var = sc.array(dims=['x', 'y'], values=[[1, 2, 3], [4, 5, 6]])
>>> var.shape
(2, 3)

>>> sc.scalar(1.0).shape
()

property size#

Number of elements in the data (read-only).

This is the product of all dimension sizes.

Examples

>>> import scipp as sc
>>> sc.array(dims=['x'], values=[1, 2, 3]).size
3
>>> sc.array(dims=['x', 'y'], values=[[1, 2, 3], [4, 5, 6]]).size
6
>>> sc.scalar(1.0).size
1

property sizes#

dict mapping dimension labels to dimension sizes (read-only).

Examples

>>> import scipp as sc
>>> var = sc.array(dims=['x', 'y'], values=[[1, 2, 3], [4, 5, 6]])
>>> var.sizes
{'x': 2, 'y': 3}

>>> da = sc.DataArray(
...     sc.array(dims=['time', 'channel'], values=[[1, 2], [3, 4], [5, 6]])
... )
>>> da.sizes
{'time': 3, 'channel': 2}

squeeze(dim=None)#

Remove dimensions of length 1.

Seealso:: Details in scipp.squeeze()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

std(dim=None, *, ddof)#

Compute the standard deviation of the input values.

Seealso:: Details in scipp.std()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

sum(dim=None)#

Sum of elements in the input.

Seealso:: Details in scipp.sum()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

to(*, unit=None, dtype=None, copy=True)#

Converts a Variable or DataArray to a different dtype and/or a different unit.

If the dtype and unit are both unchanged and copy is False, the object is returned without making a deep copy.

This method will choose whether to do the dtype or units translation first, by using the following rules in order:

If either the input or output dtype is float64, the unit translation will be done on the float64 type
If either the input or output dtype is float32, the unit translation will be done on the float32 type
If both the input and output dtypes are integer types, the unit translation will be done on the larger type
In other cases, the dtype is converted first and then the unit translation is done

Parameters:

unit (Unit | str | None, default: None) – Target unit. If None, the unit is unchanged.
dtype (Any | None, default: None) – Target dtype. If None, the dtype is unchanged.
copy (bool, default: True) – If False, return the input object if possible. If True, the function always returns a new object.

Returns:

Same as input – New object with specified dtype and unit.

Raises:

scipp.DTypeError – If the input cannot be converted to the given dtype.
scipp.UnitError – If the input cannot be converted to the given unit.

Examples

Convert units only:

>>> import scipp as sc
>>> var = sc.array(dims=['x'], values=[1000.0, 2000.0], unit='m')
>>> var.to(unit='km')
<scipp.Variable> (x: 2)    float64             [km]  [1, 2]

Convert dtype only:

>>> var_int = sc.array(dims=['x'], values=[1, 2, 3])
>>> var_int.to(dtype='float64')
<scipp.Variable> (x: 3)    float64  [dimensionless]  [1, 2, 3]

Convert both unit and dtype:

>>> var_m = sc.array(dims=['x'], values=[1000, 2000, 3000], unit='m')
>>> var_m.to(unit='km', dtype='float32')
<scipp.Variable> (x: 3)    float32             [km]  [1, 2, 3]

transform_coords(targets=None, /, graph=None, *, rename_dims=True, keep_aliases=True, keep_intermediate=True, keep_inputs=True, quiet=False, **kwargs)#

Compute new coords based on transformations of input coords.

Seealso:: Details in scipp.transform_coords()
Return type:: TypeVar(_T, DataArray, Dataset)

transpose(dims=None)#

Transpose dimensions of the input.

Seealso:: Details in scipp.transpose()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

underlying_size(self: scipp._scipp.core.DataArray) → int#

Return the size of the object in bytes.

The size includes the object itself and all arrays contained in it. But arrays may be counted multiple times if components share buffers, e.g. multiple coordinates referencing the same memory. Conversely, the size may be underestimated. Especially, but not only, with dtype=PyObject.

This function includes all memory of the underlying buffers. Use __sizeof__ to get the size of the current slice only.

property unit#

Physical unit of the data.

Examples

>>> import scipp as sc
>>> var = sc.array(dims=['x'], values=[1.0, 2.0, 3.0], unit='m')
>>> var.unit
Unit(m)
>>> var.unit = 'cm'
>>> var
<scipp.Variable> (x: 3)    float64             [cm]  [1, 2, 3]

Note: Changing the unit does not convert the values.

property value#

The only value for 0-dimensional data, raising an exception if the data is not 0-dimensional.

Use this property to access or modify the single value of a scalar (0-D) variable. For multi-dimensional data, use values instead.

Examples

>>> import scipp as sc
>>> import numpy as np
>>> scalar = sc.scalar(3.14, unit='rad')
>>> scalar.value
np.float64(3.14)
>>> scalar.value = 2.0
>>> scalar
<scipp.Variable> ()    float64            [rad]  2

Integer scalars return numpy scalar types:

>>> int_scalar = sc.scalar(42)
>>> int_scalar.value
np.int64(42)

property values#

Array of values of the data.

Returns a NumPy array that shares memory with the variable’s data buffer. Modifications to the array will affect the variable and vice versa.

Examples

>>> import scipp as sc
>>> var = sc.array(dims=['x'], values=[1.0, 2.0, 3.0], unit='m')
>>> var.values
array([1., 2., 3.])
>>> type(var.values)
<class 'numpy.ndarray'>

Values can be modified in place:

>>> var.values[0] = 10.0
>>> var
<scipp.Variable> (x: 3)    float64              [m]  [10, 2, 3]

Or replaced entirely:

>>> var.values = [4.0, 5.0, 6.0]
>>> var
<scipp.Variable> (x: 3)    float64              [m]  [4, 5, 6]

var(dim=None, *, ddof)#

Compute the variance of the input values.

Seealso:: Details in scipp.var()
Return type:: TypeVar(VariableLikeType, Variable, DataArray, Dataset, DataGroup[Any])

property variance#

The only variance for 0-dimensional data, raising an exception if the data is not 0-dimensional.

Use this property to access or modify the single variance of a scalar (0-D) variable. Returns None if the variable has no variances. For multi-dimensional data, use variances instead.

Examples

>>> import scipp as sc
>>> import numpy as np
>>> scalar = sc.scalar(5.0, variance=0.5)
>>> scalar.variance
np.float64(0.5)
>>> scalar.variance = 0.1
>>> scalar
<scipp.Variable> ()    float64  [dimensionless]  5  0.1

Scalars without variance return None:

>>> sc.scalar(5.0).variance is None
True

property variances#

Array of variances of the data.

Returns a NumPy array that shares memory with the variable’s variance buffer, or None if the variable has no variances.

Examples

>>> import scipp as sc
>>> var = sc.array(dims=['x'], values=[1.0, 2.0, 3.0], variances=[0.1, 0.2, 0.3])
>>> var.variances
array([0.1, 0.2, 0.3])

Variables without variances return None:

>>> var_no_var = sc.array(dims=['x'], values=[1.0, 2.0, 3.0])
>>> var_no_var.variances is None
True

Variances can be set or removed:

>>> var_no_var.variances = [0.01, 0.02, 0.03]
>>> var_no_var.variances
array([0.01, 0.02, 0.03])
>>> var_no_var.variances = None
>>> var_no_var.variances is None
True

This Page

scipp.DataArray#