cedalion.xrutils

Utility functions for xarray objects.

Functions

`apply_mask`(data_array, mask, operator, ...)	Apply a boolean mask to a DataArray according to the defined "operator".
`convolve`(data_array, kernel, dim)	Convolve a DataArray along a given dimension "dim" with a "kernel".
`coords_from_other`(source[, dims])	Create a dictionary of coordinates from source for matching dims in target.
`drop_duplicate_dimensions`(array)	Remove dimensions in which all array values are identical.
`mask`(array, initval)	Create a boolean mask array with the same shape as the input array.
`norm`(array, dim)	Calculate the vector norm along a given dimension.
`other_dim`(data_array, *dims)	Get the dimension name not listed in *dims.
`pinv`(array)	Calculate the pseudoinverse of a 2D xr.DataArray.
`unit_stripping_is_error`([is_error])
`unstack`(array, unstack_dim, stacked_dims)	Unstack a stacked DataArray.

cedalion.xrutils.pinv(array: DataArray) → DataArray[source]

Calculate the pseudoinverse of a 2D xr.DataArray.

FIXME: handles unitless and quantified DataArrays but not: DataArrays with units in their attrs.

Parameters:: array (xr.DataArray) – Input array
Returns:: Pseudoinverse of the input array
Return type:: array_inv (xr.DataArray)

cedalion.xrutils.norm( array: DataArray, dim: str, ) → DataArray[source]

Calculate the vector norm along a given dimension.

Extends the behavior of numpy.linalg.norm to xarray DataArrays.

Parameters:

array (xr.DataArray) – Input array
dim (str) – Dimension along which to calculate the norm

Returns:

Array with the norm along the specified dimension

Return type:

normed (xr.DataArray)

cedalion.xrutils.mask( array: DataArray, initval: bool, ) → DataArray[source]: Create a boolean mask array with the same shape as the input array.

cedalion.xrutils.apply_mask( data_array: DataArray, mask: DataArray, operator: str, dim_collapse: str, ) → DataArray[source]

Apply a boolean mask to a DataArray according to the defined “operator”.

Parameters:

data_array – NDTimeSeries, input time series data xarray
mask – input boolean mask array with a subset of dimensions matching data_array
operator – operators to apply to the mask and data_array “nan”: inserts NaNs in the data_array where mask is False “drop”: drops value in the data_array where mask is False
dim_collapse – Mask dimension to collapse to, merging boolean masks along all other dimensions. Can be skipped with “none”. Example: collapsing to “channel” dimension will drop or nan a channel if it is “False” along any other dimensions

Returns:

Input data_array with applied mask masked_elements: List of elements in data_array that were masked (e.g.

dropped or set to NaN)

Return type:

masked_data_array

cedalion.xrutils.convolve( data_array: DataArray, kernel: ndarray, dim: str, ) → DataArray[source]: Convolve a DataArray along a given dimension “dim” with a “kernel”.

cedalion.xrutils.other_dim(data_array: DataArray, *dims: str) → str[source]

Get the dimension name not listed in *dims.

Checks that there is only one more dimension than given in dims and returns its name.

Parameters:

data_array – an xr.DataArray
*dims – names of dimensions

Returns:

The name of the dimension of data_array.

cedalion.xrutils.coords_from_other(

source: DataArray,

dims: list[str] = None,

**aux_coords,

) → dict[str, tuple[str, DataArray]][source]

Create a dictionary of coordinates from source for matching dims in target.

Parameters:

source – the DataArray to copy the coordinates from.
dims – a list of dimensions names. If specified, copy only coords for those dims.
aux_coords – additional key-value pairs to add to the resulting coords dict.

Returns:

A dictionary that can be passed to DataArray.assign_coords.

cedalion.xrutils.unit_stripping_is_error(is_error: bool = True)[source]

cedalion.xrutils.drop_duplicate_dimensions( array: DataArray, ) → DataArray[source]

Remove dimensions in which all array values are identical.

During stacking and unstacking of dimensions, coordinate arrays can occur that are attributed to multiple dimensions although their values change only along a single dimensions. This function reduces the array to that single dimension.

cedalion.xrutils.unstack( array: DataArray, unstack_dim: str, stacked_dims: tuple[str], ) → DataArray[source]

Unstack a stacked DataArray.

This function unstacks a DataArray in which dimensions ‘stacked_dims’ have been stacked into the dimension ‘unstack_dim’. The function further processes unstacked coordinate arrays, so that they are attributed only to their respective dimension.

Parameters:

array – the stacked DataArray
unstack_dim – the dimension to unstack
stacked_dims – The dimensions that were stacked together in the order given to DataArray.stack.

Returns:

The unstacked array.