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: Optional[Union[str, scipp._scipp.core.Unit]] = None, 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().

Parameters
  • dims (Sequence[str]) – Dimension labels.

  • values (numpy.ArrayLike) – Sequence of values for constructing an array variable.

  • variances (numpy.ArrayLike) – Sequence of variances for constructing an array variable.

  • value (Any) – A single value for constructing a scalar variable.

  • variance (Any) – A single variance for constructing a scalar variable.

  • unit (scipp.Unit) – Physical unit, defaults to scipp.units.dimensionless.

  • dtype (Any) – Type of the variable’s elements. Is deduced from other arguments in most cases. Defaults to sc.dtype.float64 if no deduction is possible.

Seealso

Specialized creation functions, in particular scipp.array() and scipp.scalar().

Methods

__init__(self, *, dims[, values, variances, ...])

Initialize a variable with values and/or variances.

all([dim, out])

Element-wise AND over the specified dimension or all dimensions if not provided.

any([dim, out])

Element-wise OR over the specified dimension or all dimensions if not provided.

astype(self, type, *[, copy])

Converts a Variable or DataArray to a different dtype.

broadcast(dims, shape)

Broadcast a variable.

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 of a variable or data array 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.

max([dim, out])

Element-wise max over the specified dimension or all dimensions if not provided.

mean([dim, out])

Element-wise mean over the specified dimension.

min([dim, out])

Element-wise min over the specified dimension or all dimensions if not provided.

nanmax([dim, out])

Element-wise max ignoring not a number values over the specified dimension or all dimensions if not provided.

nanmean([dim, out])

Element-wise mean over the specified dimension ignoring NaNs.

nanmin([dim, out])

Element-wise min ignoring not at number values over the specified dimension or all dimensions if not provided.

nansum([dim, out])

Element-wise sum over the specified dimension; NaNs ignored.

plot(**kwargs)

Plot a Scipp object.

rename_dims(self, dims_dict)

Rename dimensions.

round(*[, out])

Round to the nearest integer if all values passed in x.

sum([dim, out])

Element-wise sum over the specified dimension.

to_hdf5(filename)

Writes object out to file in hdf5 format.

transpose([dims])

Transpose dimensions of a variable, an data array, or a dataset.

underlying_size(self)

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.

events

Returns the data underlying the bins stored in the object, or None if the object stores dense data.

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

Makes a dictionary of dimensions labels to dimension sizes

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.

all(dim=None, *, out=None)

Element-wise AND over the specified dimension or all dimensions if not provided.

Seealso

Details in scipp.all()

Parameters
Return type

scipp._scipp.core.Variable

any(dim=None, *, out=None)

Element-wise OR over the specified dimension or all dimensions if not provided.

Seealso

Details in scipp.any()

Parameters
Return type

scipp._scipp.core.Variable

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]

property bins

Returns helper scipp.Bins allowing bin-wise operations to be performed or None if not binned data.

broadcast(dims, shape)

Broadcast a variable.

Seealso

Details in scipp.broadcast()

Parameters
Return type

scipp._scipp.core.Variable

ceil(*, out=None)

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

Seealso

Details in scipp.ceil()

Parameters
  • x (VariableLike) –

  • out (Optional[VariableLike]) –

Return type

VariableLike

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()

Parameters
Return type

scipp._scipp.core.Variable

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 events

Returns the data underlying the bins stored in the object, or None if the object stores dense data.

property fields

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

flatten(dims=None, to=None)

Flatten multiple dimensions of a variable or data array into a single dimension. If dims is omitted, then we flatten all of the inputs dimensions into a single dim.

Seealso

Details in scipp.flatten()

Parameters
  • x (VariableLike) –

  • dims (Optional[Union[List[str], Tuple[str]]]) –

  • to (Optional[str]) –

Return type

VariableLike

floor(*, out=None)

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

Seealso

Details in scipp.floor()

Parameters
  • x (VariableLike) –

  • out (Optional[VariableLike]) –

Return type

VariableLike

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()

Parameters
  • x (VariableLike) –

  • dim (str) –

  • sizes (Optional[Dict[str, int]]) –

  • dims (Optional[Union[List[str], Tuple[str]]]) –

  • shape (Optional[Sequence[int]]) –

Return type

VariableLike

max(dim=None, *, out=None)

Element-wise max over the specified dimension or all dimensions if not provided.

Seealso

Details in scipp.max()

Parameters
Return type

scipp._scipp.core.Variable

mean(dim=None, *, out=None)

Element-wise mean over the specified dimension.

Seealso

Details in scipp.mean()

Parameters
  • x (VariableLike) –

  • dim (Optional[str]) –

  • out (Optional[VariableLike]) –

Return type

VariableLike

min(dim=None, *, out=None)

Element-wise min over the specified dimension or all dimensions if not provided.

Seealso

Details in scipp.min()

Parameters
Return type

scipp._scipp.core.Variable

nanmax(dim=None, *, out=None)

Element-wise max ignoring not a number values over the specified dimension or all dimensions if not provided.

Seealso

Details in scipp.nanmax()

Parameters
Return type

scipp._scipp.core.Variable

nanmean(dim=None, *, out=None)

Element-wise mean over the specified dimension ignoring NaNs.

Seealso

Details in scipp.nanmean()

Parameters
  • x (VariableLike) –

  • dim (Optional[str]) –

  • out (Optional[VariableLike]) –

Return type

VariableLike

nanmin(dim=None, *, out=None)

Element-wise min ignoring not at number values over the specified dimension or all dimensions if not provided.

Seealso

Details in scipp.nanmin()

Parameters
Return type

scipp._scipp.core.Variable

nansum(dim=None, *, out=None)

Element-wise sum over the specified dimension; NaNs ignored.

Seealso

Details in scipp.nansum()

Parameters
  • x (VariableLike) –

  • dim (Optional[str]) –

  • out (Optional[VariableLike]) –

Return type

VariableLike

property ndim

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

plot(**kwargs)

Plot a Scipp object.

Possible inputs are: - Variable - DataArray - Dataset - dict of Variables - dict of DataArrays

For more details, see https://scipp.github.io/visualization/plotting-overview.html

Parameters
  • aspect (str, optional) – Specify the aspect ratio for 2d images. Possible values are “auto” or “equal”. Defaults to “auto”.

  • ax (matplotlib.axes.Axes, optional) – Attach returned plot to supplied Matplotlib axes (1d and 2d only). Defaults to None.

  • labels (dict, optional) – Dict specifying which coordinate should be used to label the tics for a dimension. If not specifified the dimension coordinate is used. labels={“time”: “time-labels”}. Defaults to None.

  • cax (matplotlib.axes.Axes, optional) – Attach colorbar to supplied Matplotlib axes. Defaults to None.

  • cmap (str, optional) – Matplotlib colormap (2d and 3d only). See https://matplotlib.org/tutorials/colors/colormaps.html. Defaults to None.

  • color (str, optional) – Matplotlib line color (1d only). See https://matplotlib.org/tutorials/colors/colors.html. Defaults to None.

  • errorbars (str or dict, optional) – Show errorbars if True, hide them if False (1d only). Defaults to True. This can also be a dict of bool where the keys correspond to data entries.

  • figsize (tuple, optional) – The size of the figure in inches (1d and 2d only). See https://matplotlib.org/api/_as_gen/matplotlib.pyplot.figure.html. Defaults to None.

  • filename (str, optional) – If specified, the figure will be saved to disk. Possible file extensions are .jpg, .png and .pdf. The default directory for writing the file is the same as the directory where the script or notebook is running. Defaults to None.

  • grid (bool, optional) – Show grid on axes if True. Defaults to False.

  • linestyle (str, optional) – Matplotlib linestyle (1d only). See https://matplotlib.org/gallery/lines_bars_and_markers/linestyles.html. Defaults to “none”.

  • marker (str, optional) – Matplotlib line marker (1d only). See https://matplotlib.org/api/markers_api.html. Defaults to ‘o’.

  • masks (dict, optional) – A dict to hold display parameters for masks such as a color or a cmap. Defaults to None.

  • norm (str, optional) – Normalization of the data. Possible choices are “linear” and “log”. Defaults to “linear”.

  • pax (matplotlib.axes.Axes, optional) – Attach profile plot to supplied Matplotlib axes. Defaults to None.

  • pixel_size (float, optional) – Specify the size of the pixels to be used for the point cloud (3d only). If none is supplied, the size is guessed based on the extents of the data in the 3d space. Defaults to None.

  • positions (Variable, optional) – Specify an array of position vectors to be used as scatter points positions (3d only). Defaults to None.

  • projection (str, optional) – Specify the projection to be used. Possible choices are “1d”, “2d”, or “3d”. Defaults to “2d” if the number of dimensions of the input is >= 2.

  • resampling_mode (str, optional) – Resampling mode. Possible choices are “sum” and “mean”. This applies only to binned event data and non-1d data. Defaults to “mean” unless the unit is ‘counts’ or ‘dimensionless’.

  • scale (dict, optional) – Specify the scale (“linear” or “log”) for a displayed dimension axis. E.g. scale={“tof”: “log”}. Defaults to None.

  • vmin (float, optional) – Minimum value for the y-axis (1d) or colorscale (2d and 3d). Defaults to None.

  • vmax (float, optional) – Maximum value for the y-axis (1d) or colorscale (2d and 3d). Defaults to None.

rename_dims(self: scipp._scipp.core.Variable, dims_dict: Dict[scipp._scipp.core.Dim, scipp._scipp.core.Dim]) scipp._scipp.core.Variable

Rename dimensions.

round(*, out=None)

Round to the nearest integer if all values passed in x.

Seealso

Details in scipp.round()

Parameters
  • x (VariableLike) –

  • out (Optional[VariableLike]) –

Return type

VariableLike

property shape

Shape of the data (read-only).

property sizes

Makes a dictionary of dimensions labels to dimension sizes

sum(dim=None, *, out=None)

Element-wise sum over the specified dimension.

Seealso

Details in scipp.sum()

Parameters
  • x (VariableLike) –

  • dim (Optional[str]) –

  • out (Optional[VariableLike]) –

Return type

VariableLike

to_hdf5(filename)

Writes object out to file in hdf5 format.

Parameters
transpose(dims=None)

Transpose dimensions of a variable, an data array, or a dataset.

Seealso

Details in scipp.transpose()

Parameters
  • x (VariableLike) –

  • dims (Optional[Union[List[str], Tuple[str]]]) –

Return type

VariableLike

underlying_size(self: scipp._scipp.core.Variable) int
property unit

Physical unit of the data.

property value

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

property values

Array of values of the data.

property variance

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

property variances

Array of variances of the data.