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

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)

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.

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

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 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(**kwargs)#

Plot a Scipp object.

Possible inputs are:
  • Variable

  • Dataset

  • DataArray

  • numpy ndarray

  • dict of Variables

  • dict of DataArrays

  • dict of numpy ndarrays

  • dict that can be converted to a Scipp object via from_dict

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.

  • camera (dict, optional) – Dict configuring the camera. Valid entries are ‘position’ and ‘look_at’. This option is valid only for 3-D scatter plots. The ‘position’ entry defines the position of the camera and the ‘look_at’ entry defines the point the camera is looking at. Both must be variables containing a single vector with the correct unit, i.e., a unit compatible with the unit of the scatter point positions. Defaults to None, in which case the camera looks at the center of the cloud of plotted points.

  • 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_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.

See also

scipp.Variable.rename_dims

Equivalent for Variable but differs for DataArray and Dataset.

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 (Optional[Dict[str, str]], default: None) – Dictionary mapping old to new names.

  • names (str) – Mapping of old to new names as keyword arguments.

Returns

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

round(*, out=None)#

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

Seealso

Details in scipp.round()

Return type

Union[Variable, DataArray, Dataset]

property shape#

Shape of the data (read-only).

property sizes#

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

squeeze(dim=None)#

Remove dimensions of length 1.

Seealso

Details in scipp.squeeze()

Return type

TypeVar(VariableLikeType, Variable, DataArray, Dataset)

sum(dim=None)#

Sum of elements in the input.

Seealso

Details in scipp.sum()

Return type

TypeVar(VariableLikeType, Variable, DataArray, Dataset)

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 (Union[Unit, str, None], default: None) – Target unit. If None, the unit is unchanged.

  • dtype (Optional[Any], 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
to_hdf5(filename)#

Writes object out to file in hdf5 format.

transpose(dims=None)#

Transpose dimensions of the input.

Seealso

Details in scipp.transpose()

Return type

TypeVar(VariableLikeType, Variable, DataArray, Dataset)

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.