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.

check_units(array, dimension)

Return whether array has physical units compatible with dimension.

compose_affine(A, B)

Compose two affine transforms using the [to_crs, from_crs] convention.

contract(a1, a2, dim)

Apply xr.dot after asserting compatible shapes.

convolve(data_array, kernel, dim)

Convolve a DataArray with a 1-D kernel along the specified dimension.

coords_from_other(source[, dims])

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

dot_dataarray_csr(a, b, bdims)

Multiply a dense DataArray by a sparse matrix along their shared dimension.

drop_duplicate_dimensions(array)

Remove constant dimensions from array, keeping only those that vary.

mask(array, initval)

Create a boolean mask DataArray with the same shape as 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.

transpose_like(a, target[, dim_map])

Transpose a so its dimension order matches that of target.

unit_stripping_is_error([is_error])

Promote UnitStrippedWarning to an exception (or revert that promotion).

unit_stripping_is_quiet([is_quiet])

Suppress UnitStrippedWarning globally (or restore the default behaviour).

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.compose_affine(
A: DataArray,
B: DataArray,
) → DataArray[source]

Compose two affine transforms using the [to_crs, from_crs] convention.

Equivalent to numpy A @ B: contracts A’s from_crs against B’s to_crs and returns a transform with dims [A.dims[0], B.dims[1]].

Using xarray’s @ / xr.dot directly is unsafe here because it contracts over every shared dim name, so e.g. composing ["ijk","mni"] with ["mni","ijk"] collapses both dims and returns a scalar instead of a 4x4 matrix.

Parameters:

  • A – 4x4 affine transform with dims [to_crs_A, from_crs_A].

  • B – 4x4 affine transform with dims [to_crs_B, from_crs_B].

Returns:

4x4 affine transform with dims [A.dims[0], B.dims[1]]. Units are the product of A’s and B’s pint units (so the inner unit cancels for the to/from convention).

Raises:

ValueError – If either operand is not 2D / 4x4, or if the inner-dim names don’t chain (A.dims[1] != B.dims[0]).

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 DataArray with the same shape as array.

Parameters:

  • array – Template DataArray whose shape, dims, and coords are copied.

  • initval – Initial boolean value to fill the mask with (True or False).

Returns:

A boolean DataArray with the same shape and coordinates as 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 – Input NDTimeSeries (xr.DataArray).

  • mask – Boolean mask array whose dimensions must be a subset of data_array’s dimensions.

  • operator – How to apply the mask. "nan" inserts NaN where the mask is False; "drop" removes those elements entirely.

  • dim_collapse – Mask dimension to collapse to, merging boolean values along all other dimensions before applying. Pass "none" to skip collapsing. For example, collapsing to "channel" will drop or NaN an entire channel if it is False along any other dimension.

Returns:

A tuple (masked_data_array, masked_elements) where masked_data_array is the input array with the mask applied, and masked_elements is a list of the masked label values (when dim_collapse is not "none") or the string "N/A" otherwise.

cedalion.xrutils.convolve(
data_array: DataArray,
kernel: ndarray,
dim: str,
) → DataArray[source]

Convolve a DataArray with a 1-D kernel along the specified dimension.

Uses np.convolve in "same" mode so the output has the same length as the input along dim. Pint units are preserved.

Parameters:

  • data_array – Input DataArray. May be unit-quantified.

  • kernel – 1-D convolution kernel.

  • dim – Name of the dimension along which to convolve.

Returns:

Convolved DataArray with the same shape, dims, and units as data_array.

Raises:

ValueError – If dim is not a dimension of data_array.

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

Get the dimension name not listed in dims.

Checks that there is exactly one more dimension in data_array than the number of names supplied in dims and returns its name.

Parameters:

  • data_array – Input DataArray.

  • *dims – Names of dimensions to exclude.

Returns:

Name of the single remaining dimension not listed in dims.

Raises:

ValueError – If data_array does not have exactly len(dims) + 1 dimensions, or if any of the supplied dims are not present.

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]

Promote UnitStrippedWarning to an exception (or revert that promotion).

Useful for debugging: once raised as an error, the debugger can pinpoint the exact cedalion or third-party call that silently drops pint units.

Parameters:

is_error – If True (default), convert the warning to an error. If False, remove the error filter so the warning is emitted normally.

cedalion.xrutils.unit_stripping_is_quiet(is_quiet: bool = True)[source]

Suppress UnitStrippedWarning globally (or restore the default behaviour).

Not recommended for production code. Prefer unit_stripping_is_error() to locate and fix the source of the warning rather than silencing it.

Parameters:

is_quiet – If True (default), add an "ignore" filter for the warning. If False, remove any such filter.

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

Remove constant dimensions from array, keeping only those that vary.

After stacking and unstacking, coordinate arrays are sometimes attributed to multiple dimensions even though their values only change along a single one. This function drops any dimension where all values are identical (i.e. the coordinate is effectively scalar along that dimension).

Parameters:

array – DataArray that may contain constant dimensions introduced by stacking/unstacking operations.

Returns:

DataArray with constant dimensions removed and their scalar coordinates dropped.

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.

cedalion.xrutils.contract(
a1: DataArray,
a2: DataArray,
dim: str | list[str],
) → DataArray[source]

Apply xr.dot after asserting compatible shapes.

xr.dot will silently multiply arrays along dimensions which differ in shape if these arrays have an overlap in coordinates. This function requires an exact match in coordinates before calling xr.dot.

Parameters:

  • a1 – first operand

  • a2 – second operand

  • dim – dimension(s) to contract over

Returns:

the result of xr.dot.

cedalion.xrutils.transpose_like(
a: DataArray,
target: DataArray,
dim_map: dict[str, str] | None = None,
) → DataArray[source]

Transpose a so its dimension order matches that of target.

Parameters:

  • a – DataArray to reorder.

  • target – DataArray whose dimension order is used as the reference.

  • dim_map – Optional mapping from dimension names in a to their corresponding names in target, for dimensions that have been renamed between the two arrays.

Returns:

View of a with dimensions reordered to match target.

Raises:

ValueError – If a dimension of a cannot be found in target (even after applying dim_map).

cedalion.xrutils.dot_dataarray_csr(a: ~xarray.core.dataarray.DataArray, b: <module 'scipy.sparse' from '/home/runner/miniconda3/envs/cedalion/lib/python3.11/site-packages/scipy/sparse/__init__.py'>, bdims: list[str, str]) → DataArray[source]

Multiply a dense DataArray by a sparse matrix along their shared dimension.

The shared dimension is inferred from the overlap between a’s dims and bdims. All other dimensions of a are kept intact. The result has the same non-contracted dimensions as a plus the remaining dimension of b.

Parameters:

  • a – Dense DataArray. Must share exactly one dimension with bdims.

  • b – Sparse matrix (CSR or compatible SciPy sparse format).

  • bdims – Two-element list naming the row and column dimensions of b, e.g. ["vertex", "channel"].

Returns:

Dense DataArray resulting from the contraction. Dimension order matches the original ordering in a (with the contracted dim replaced by the remaining dim of b).

Raises:

ValueError – If a and b do not share exactly one dimension, or if the sizes along the shared dimension do not match.

cedalion.xrutils.check_units(array: DataArray, dimension: str) → bool[source]

Return whether array has physical units compatible with dimension.

Works for both quantified DataArrays (array.pint.units is set) and dequantified ones (units stored in array.attrs["units"]).

Parameters:

  • array – DataArray to check.

  • dimension – Pint dimensionality string, e.g. "[length]", "[time]", "[concentration]".

Returns:

True if the array’s units are dimensionally compatible with dimension, False if the array carries no unit information.