`xarray` Extensions

“Custom accessors”, are defined to provide additional functionality to xarray.DataArray and xarray.Dataset objects. These accessors group methods under the namespace indica. E.g.:

data_array.indica.remap_like(array2)
data_array.indica.check_datatype(("temperature", "electron"))
dataset.indica.check_datatype(("electron", {"T": "temperature",
                                            "n": "number_density"}))

class indica.data.InDiCAArrayAccessor(xarray_obj)[source]

Class providing additional functionality to xarray.DataArray objects which is useful for this software.

Parameters: xarray_obj (xarray.core.dataarray.DataArray) –

check_datatype(data_type)[source]

Checks that the data type of this xarray.DataArray matches the argument.

Parameters

data_type (Tuple[Optional[str], Optional[str]]) – The datatype to check this array against.

Returns

status – Whether the datatype of this array matches the argument.
message – If status == False, an explanation of why.

Return type

Tuple[bool, Optional[str]]

convert_coords(transform)[source]

Convert this array’s coordinates to those of the coordinate system transform. The result will be cached for future reuse.

Parameters

transform (indica.converters.abstractconverter.CoordinateTransform) – The transform describing the coordinate system to which the coordiantes will be converted.

Returns

x1 (LabeledArray) – The first spatial coordinate in the new system
x2 (LabeledArray) – The second spatial coordinate in the new system

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

property drop_dim: Optional[str]: The dimension, if any, which contains dropped channels.

property equilibrium: Optional[indica.equilibrium.Equilibrium]: The equilibrium object currently used by this DataArray (or, more accurately, by its CoordinateTransform object). When setting or deleting this porperty, ensures provenance will be updated accordingly.

get_coords(transform=None)[source]

Get this array’s coordinates, including time, in the coordinate system transform. The result will be cached for future reuse.

Parameters

transform (Optional[indica.converters.abstractconverter.CoordinateTransform]) – The transform describing the coordinate system to which the coordiantes will be converted.

Returns

x1 (LabeledArray) – The first spatial coordinate in the new system
x2 (LabeledArray) – The second spatial coordinate in the new system
t (LabeledArray) – The time coordinate

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

ignore_data(labels, dimension)[source]

Create a copy of this array which masks the specified data.

Parameters

labels (Union[numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]) – The channel labels for which data should be ignored.
dimension (str) – The name of the dimension the labels are along

Returns

A copy of this object, but with data for the specified labels along the specified dimension marked as NaN.

Return type

xarray.core.dataarray.DataArray

inclusive_timeslice(t_start, t_end)[source]

Returns a view into this xarray.DataArray containing t_start and t_end.

Parameters

t_start (float) – The smallest time value to be included
t_end (float) – The largest time value to be included

Return type

View of DataArray containing range t_start and t_end

interp2d(coords=None, zero_coords=None, method='linear', assume_sorted=False, **coords_kwargs)[source]

Performs interpolation along two dimensions simultatiously. Unlike xarray.DataArray.interp(), this routine supports higher-order interpolation than linear by usinmg scipy.interpolate.RectBivariateSpline() (although with potentially-inefficient vectorisation). All options are the same as in the xarray method. However, interpolation will not be performed on any of the non-dimensional coordinates, unlike in the xarray method.

Parameters

coords (Optional[Mapping[Hashable, Union[numpy._typing._array_like._SupportsArray[numpy.dtype], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]]]) – A mapping from dimension names to new coordinates onto which to interpolate data. New coordinate can be a scalar, array-like or DataArray. If DataArrays are passed as new coordinates, their dimensions are used for the broadcasting. Missing values are skipped.
zero_coords (Optional[Mapping[Hashable, Union[numpy._typing._array_like._SupportsArray[numpy.dtype], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]]]) – Coordinates for any points where the data is known to be equal to zero but which are not captured by the grid.
method (Union[str, int]) – A string {“linear”, “nearest”, “quadratic”, “cubic”} or an integer indicating the degree of the splines.
assume_sorted (bool) – If False, values of coordinates that are interpolated over can be in any order and they are sorted first. If True, interpolated coordinates are assumed to be an array of monotonically increasing values.
coords_kwargs (Union[numpy._typing._array_like._SupportsArray[numpy.dtype], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]) – The keyword arguments form of coords.

Returns

A DataArray containing the positions on the target dimension at which the original DataArray has values, interpolated as necessary.

Return type

xarray.core.dataarray.DataArray

invert_interp(values, target, new_dims=None, coords=None, method='linear', assume_sorted=False, kwargs=None, **coords_kwargs)[source]

Performs an inversion to give coordinates at which the data has the specified value. Interpolation will be performed with the specified method. This approach is efficient if you need to do the inversion on a large number of values, but will only work properly if the data is monotonic on the target dimension.

Parameters

values (Union[numpy._typing._array_like._SupportsArray[numpy.dtype], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]) – The values of data at which to invert.
target (str) – The name of the dimension on which the result contains the coordinates at which values occur.
new_dims (Optional[Union[Tuple[str, ...], str]]) – The name(s) of the new dimensions introduced by inverting with values. Defaults to the name of the original DataArray. If that array does not have a name and a named dimension in values is equal to target then this argument is required.
coords (Optional[Mapping[Hashable, Union[numpy._typing._array_like._SupportsArray[numpy.dtype], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]]]) – A mapping from dimension names to new coordinates onto which to interpolate data. New coordinate can be a scalar, array-like or DataArray. If DataArrays are passed as new coordinates, their dimensions are used for the broadcasting. Missing values are skipped. The target dimension must not be present.
method (Union[Literal['linear', 'nearest', 'zero', 'slinear', 'quadratic', 'cubic', 'polynomial'], typing.Literal['barycentric', 'krog', 'pchip', 'spline', 'akima']]) – {“linear”, “nearest”} for multidimensional array, {“linear”, “nearest”, “zero”, “slinear”, “quadratic”, “cubic”} for 1-dimensional array. “linear” is used by default.
assume_sorted (bool) – If False, values of coordinates that are interpolated over can be in any order and they are sorted first. If True, interpolated coordinates are assumed to be an array of monotonically increasing values.
kwargs (Optional[Mapping[str, Any]]) – Additional keyword arguments passed to scipy’s interpolator. Valid options and their behavior depend on if 1-dimensional or multi-dimensional interpolation is used.
coords_kwargs (Union[numpy._typing._array_like._SupportsArray[numpy.dtype], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]) – The keyword arguments form of coords.

Returns

A DataArray containing the positions on the target dimension at which the original DataArray has values, interpolated as necessary.

Return type

xarray.core.dataarray.DataArray

invert_root(values, target, guess=None, new_dims=None, coords=None, method='linear', assume_sorted=False, kwargs=None, **coords_kwargs)[source]

Performs an inversion to give coordinates at which the data has the specified value. Cubic spline interpolation will be performed with the specified method and then the root(s) of the interpolant will be found. If there are multiple roots then a guess must be provided to determine which one to use.

Parameters

values (Union[numpy._typing._array_like._SupportsArray[numpy.dtype], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]) – The values of data at which to invert.
target (str) – The name of the dimension on which the result contains the coordinates at which values occur.
guess (Optional[Union[numpy._typing._array_like._SupportsArray[numpy.dtype], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]]) – An estimate of the values being solved for. If there are multiple roots then the one closest to the guess will be used.
new_dims (Optional[Union[Tuple[str, ...], str]]) – The name(s) of the new dimensions introduced by inverting with values. Defaults to the name of the original DataArray. If that array does not have a name and a named dimension in values is equal to target then this argument is required.
coords (Optional[Mapping[Hashable, Union[numpy._typing._array_like._SupportsArray[numpy.dtype], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]]]) – A mapping from dimension names to new coordinates onto which to interpolate data. New coordinate can be a scalar, array-like or DataArray. If DataArrays are passed as new coordinates, their dimensions are used for the broadcasting. Missing values are skipped. The target dimension must not be present.
method (Union[Literal['linear', 'nearest', 'zero', 'slinear', 'quadratic', 'cubic', 'polynomial'], typing.Literal['barycentric', 'krog', 'pchip', 'spline', 'akima']]) – {“linear”, “nearest”} for multidimensional array, {“linear”, “nearest”, “zero”, “slinear”, “quadratic”, “cubic”} for 1-dimensional array. “linear” is used by default. Only applies for interpolation onto coords.
assume_sorted (bool) – If False, values of coordinates that are interpolated over can be in any order and they are sorted first. If True, interpolated coordinates are assumed to be an array of monotonically increasing values.
kwargs (Optional[Mapping[str, Any]]) – Additional keyword arguments passed to scipy’s interpolator. Valid options and their behavior depend on if 1-dimensional or multi-dimensional interpolation is used.
coords_kwargs (Union[numpy._typing._array_like._SupportsArray[numpy.dtype], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]) – The keyword arguments form of coords.

Returns

A DataArray containing the positions on the target dimension at which the original DataArray has values, interpolated as necessary.

Return type

xarray.core.dataarray.DataArray

remap_like(other)[source]

Remap and interpolate the data in this array onto a new coordinate system.

Parameters: other (xarray.core.dataarray.DataArray) – An array whose coordinate system will be mapped onto.
Returns: An array representing the same data as this one, but interpolated so that it is on the coordinate system of other.
Return type: xarray.core.dataarray.DataArray

with_Rz_coords()[source]

Returns a DataArray containing this data plus the R-z coordinates of the data.

Note: This method relies on default coordinates for conversion to R-z being same as the coordinates used by the DataArray.

Return type: xarray.core.dataarray.DataArray

property with_ignored_data: xarray.core.dataarray.DataArray: The full version of this data, including the channels which were dropped at read-in.

class indica.data.InDiCADatasetAccessor(xarray_obj)[source]

Class providing additional functionality to xarray.Dataset objects which is useful for this software.

Parameters: xarray_obj (xarray.core.dataset.Dataset) –

attach(key, array, overwrite=False, sess=<indica.session.Session object>)[source]

Adds an additional xarray.DataArray to this xarray.Dataset. This dataset must be used for aggregating data with the same specific datatype (see SPECIFIC_DATATYPES).

It will update the metadata (datatype and provenance) to ensure the new DataArray is correctly included. If there is already an item with that key then it will raise an exception (unless the value is the same). This behaviour can be overridden with the overwrite argument.

This function will fail if the specific datatype for array differs from that for this Dataset. It will also fail if the dimensions of array differ from those of the Dataset.

Parameters

key (str) – The label which will map to the new data
array (xarray.core.dataarray.DataArray) – The data to be added to this xarray.Dataset
overwrite (bool) – If True and key already exists in this Dataset then overwrite the old value. Otherwise raise an error.
sess (indica.session.Session) – An object representing the session being run. Contains information such as provenance data.

check_datatype(datatype)[source]

Checks that the data type of this xarray.DataArray matches the argument.

This checks that all of the key/value pairs present in datatype match those in this Dataset. It will still return True even if there are _additional_ members of this dataset not included in datatype.

Parameters

datatype (Tuple[Optional[str], Dict[str, str]]) – The datatype to check this Dataset against.

Returns

status – Whether the datatype of this array matches the argument.
message – If status == False, an explanation of why.

Return type

Tuple[bool, Optional[str]]

convert_coords(transform)[source]

Convert this dataset’s coordinates to those of the coordinate system transform. The result will be cached for future reuse.

Parameters

transform (indica.converters.abstractconverter.CoordinateTransform) – The transform describing the coordinate system to which the coordiantes will be converted.

Returns

x1 (LabeledArray) – The first spatial coordinate in the new system
x2 (LabeledArray) – The second spatial coordinate in the new system

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

property datatype: Tuple[Optional[str], Dict[str, str]]: A structure describing the data contained within this Dataset.

get_coords(transform=None)[source]

Get this dataset’s coordinates, including time, in the coordinate system transform. The result will be cached for future reuse.

Parameters

transform (Optional[indica.converters.abstractconverter.CoordinateTransform]) – The transform describing the coordinate system to which the coordiantes will be converted.

Returns

x1 (LabeledArray) – The first spatial coordinate in the new system
x2 (LabeledArray) – The second spatial coordinate in the new system
t (LabeledArray) – The time coordinate

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

inclusive_timeslice(t_start, t_end)[source]

Returns a view into this xarray.Dataset containing t_start and t_end.

Parameters

t_start (float) – The smallest time value to be included
t_end (float) – The largest time value to be included

Return type

View of Dataset containing range t_start and t_end

indica.data.aggregate(sess=<indica.session.Session object>, **kwargs)[source]

Combines the key-value pairs in kwargs into a Dataset, performing various checks.

In order for this to succeed, the following must hold:

All arguments must have the same specific datatype (see SPECIFIC_DATATYPES).
All arguments must use the same coordinate system (though not all of them need to use all of the coordinates).
All arguments must use the same :py:class`CoordinateTransform` object
All arguments need to store data on the same grid (always the case for datasets)

In addition to performing these checks, this function will create the correct provenance.

Warning

This should not be used for assembling results of an Operator, as it will not provide the necessary derivation provenance.

Parameters

sess (indica.session.Session) – An object representing the session being run. Contains information such as provenance data.
kwargs (xarray.core.dataarray.DataArray) – The DataArrays to be combined into a dataset.

Return type

xarray.core.dataset.Dataset

xarray Extensions

`xarray` Extensions