scipp.Variable#

class scipp.Variable#

Array of values with dimension labels and a unit, optionally including an array of variances.

__init__(self: scipp._scipp.core.Variable, *, dims: object, values: object = None, variances: object = None, unit: Union[str, scipp._scipp.core.Unit, None, scipp._scipp.core.DefaultUnit] = <automatically deduced unit>, dtype: object = None) → None#

Initialize a variable with values and/or variances.

At least one argument of values and variances must be used. if you want to preallocate memory to fill later, use scipp.empty().

Attention

This constructor is meant primarily for internal use. Use one of the Specialized creation functions instead. See in particular scipp.array() and scipp.scalar().

Parameters

dims – Dimension labels.
values – Sequence of values for constructing an array variable.
variances – Sequence of variances for constructing an array variable.
unit – Physical unit, defaults to scipp.units.dimensionless.
dtype – Type of the variable’s elements. Is deduced from other arguments in most cases. Defaults to sc.DType.float64 if no deduction is possible.

Methods

`__init__`(self, *, dims, values, variances, ...)	Initialize a variable with values and/or variances.
`all`([dim])	Logical AND over input values.
`any`([dim])	Logical OR over input values.
`astype`(self, type, *[, copy])	Converts a Variable or DataArray to a different dtype.
`bin`([arg_dict])	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.
`cumsum`([dim, mode])	Return the cumulative sum along the specified dimension.
`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[, sizes, dims, shape])	Fold a single dimension of a variable or data array into multiple dims.
`hist`([arg_dict])	Compute a histogram.
`max`([dim])	Maximum of elements in the input.
`mean`([dim])	Arithmetic mean of elements in the input.
`min`([dim])	Minimum of elements in the input.
`nanhist`([arg_dict])	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.
`nanmin`([dim])	Minimum of elements in the input ignoring NaN's.
`nansum`([dim])	Sum of elements in the input ignoring NaN's.
`plot`([aspect, cbar, crop, errorbars, grid, ...])	Plot a Scipp object.
`rename`([dims_dict])	Rename dimension labels.
`rename_dims`([dims_dict])	Rename dimensions.
`round`(*[, out])	Round to the nearest integer of all values passed in x.
`squeeze`([dim])	Remove dimensions of length 1.
`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.
`to_hdf5`(filename)	Writes object out to file in hdf5 format.
`transpose`([dims])	Transpose dimensions of the input.
`underlying_size`(self)	Return the size of the object in bytes.

Attributes

`bins`	Returns helper `scipp.Bins` allowing bin-wise operations to be performed or None if not binned data.
`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.
`fields`	Provides access to fields of structured types such as vectors or matrices.
`ndim`	Number of dimensions of the data (read-only).
`shape`	Shape of 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.Variable, arg0: int) -> scipp._scipp.core.Variable
__getitem__(self: scipp._scipp.core.Variable, arg0: slice) -> scipp._scipp.core.Variable
__getitem__(self: scipp._scipp.core.Variable, arg0: scipp._scipp.core.Variable) -> scipp._scipp.core.Variable
__getitem__(self: scipp._scipp.core.Variable, arg0: Tuple[str, int]) -> scipp._scipp.core.Variable
__getitem__(self: scipp._scipp.core.Variable, arg0: Tuple[str, slice]) -> scipp._scipp.core.Variable
__getitem__(self: scipp._scipp.core.Variable, arg0: ellipsis) -> scipp._scipp.core.Variable
__getitem__(self: scipp._scipp.core.Variable, arg0: List[int]) -> scipp._scipp.core.Variable
__getitem__(self: scipp._scipp.core.Variable, arg0: Tuple[str, List[int]]) -> scipp._scipp.core.Variable

all(dim=None)#

Logical AND over input values.

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

any(dim=None)#

Logical OR over input values.

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

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

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]

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

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

Seealso: Details in scipp.bin()
Return type: Union[DataArray, Dataset]

property bins#: Returns helper scipp.Bins allowing bin-wise operations to be performed or None if not 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)

ceil(*, out=None)#

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

Seealso: Details in scipp.ceil()
Return type: Union[Variable, DataArray, Dataset]

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

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.

cumsum(dim=None, mode='inclusive')#

Return the cumulative sum along the specified dimension.

Seealso: Details in scipp.cumsum()
Return type: TypeVar(VariableLikeType, Variable, DataArray, Dataset)

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

property dims#: Dimension labels of the data (read-only).

property dtype#: Data type contained in the variable.

property fields#: Provides access to fields of structured types such as vectors or matrices.

flatten(dims=None, to=None)#

Flatten multiple dimensions into a single dimension.

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

floor(*, out=None)#

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

Seealso: Details in scipp.floor()
Return type: Union[Variable, DataArray, Dataset]

fold(dim, sizes=None, dims=None, shape=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)

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

Compute a histogram.

Seealso: Details in scipp.hist()
Return type: Union[DataArray, Dataset]

max(dim=None)#

Maximum of elements in the input.

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

mean(dim=None)#

Arithmetic mean of elements in the input.

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

min(dim=None)#

Minimum of elements in the input.

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

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

Compute a histogram, skipping NaN values.

Seealso: Details in scipp.nanhist()
Return type: Union[DataArray, Dataset]

nanmax(dim=None)#

Maximum of elements in the input ignoring NaN’s.

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

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)

nanmin(dim=None)#

Minimum of elements in the input ignoring NaN’s.

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

nansum(dim=None)#

Sum of elements in the input ignoring NaN’s.

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

property ndim#: Number of dimensions of the data (read-only).

plot(aspect='auto', cbar=True, crop=None, errorbars=True, grid=False, ignore_size=False, mask_color='black', norm='linear', scale=None, title=None, vmin=None, vmax=None, **kwargs)#

Plot a Scipp object.

Parameters

obj (Union[Variable, DataArray, Dataset, ndarray, Dict[str, Union[Variable, DataArray, Dataset, ndarray]]]) – The object to be plotted.
aspect (Literal[‘auto’, ‘equal’], default: 'auto') – Aspect ratio for the axes.
cbar (bool, default: True) – Show colorbar in 2d plots if True.
crop (Optional[Dict[str, Dict[str, Variable]]], default: None) – Set the axis limits. Limits should be given as a dict with one entry per dimension to be cropped. Each entry should be a nested dict containing scalar values for 'min' and/or 'max'. Example: da.plot(crop={'time': {'min': 2 * sc.Unit('s'), 'max': 40 * sc.Unit('s')}})
errorbars (bool, default: True) – Show errorbars in 1d plots if True.
grid (bool, default: False) – Show grid if True.
ignore_size (bool, default: False) – If True, skip the check that prevents the rendering of very large data objects.
mask_color (str, default: 'black') – Color of masks in 1d plots.
norm (Literal[‘linear’, ‘log’], default: 'linear') – Set to 'log' for a logarithmic y-axis (1d plots) or logarithmic colorscale (2d plots).
scale (Optional[Dict[str, str]], default: None) – Change axis scaling between log and linear. For example, specify scale={'tof': 'log'} if you want log-scale for the tof dimension.
title (Optional[str], default: None) – The figure title.
vmin (Optional[Variable], default: None) – Lower bound for data to be displayed (y-axis for 1d plots, colorscale for 2d plots).
vmax (Optional[Variable], default: None) – Upper bound for data to be displayed (y-axis for 1d plots, colorscale for 2d plots).
**kwargs – All other kwargs are directly forwarded to Matplotlib, the underlying plotting library. The underlying functions called are the following: - 1d data with a non bin-edge coordinate: plot - 1d data with a bin-edge coordinate: step - 2d data: pcolormesh

Returns

A figure.

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

Rename dimension labels.

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.

Dimensions not specified in either input are unchanged.

Parameters

dims_dict (Optional[Dict[str, str]], default: None) – Dictionary mapping old to new names.
names (str) – Mapping of old to new names as keyword arguments.

Returns

Variable – A new variable with renamed dimensions which shares a buffer with the input.