cedalion package

Subpackages

Submodules

cedalion.errors module

Cedalion-specific exceptions.

exception cedalion.errors.CRSMismatchError[source]

Bases: ValueError

Error when coordinate reference systems do not match.

classmethod unexpected_crs(expected_crs: str, found_crs: str)[source]
classmethod wrong_transform(current_crs: str, transform_crs: tuple[str])[source]

cedalion.physunits module

Builds on pint_xarray’s unit registry.

cedalion.plots module

cedalion.tasks module

cedalion.tasks.task(f: Callable)[source]

cedalion.testing module

Utilitiy functions for tests.

cedalion.testing.temporary_filename(suffix: str = None) → Iterator[Path][source]

Context that creates a temporary file, returns its name and deletes it on exit.

Using this context to create a temporay files works around the problem that on Windows an open temporary files may not be reopened again.

Adapted from https://stackoverflow.com/a/57701186.

Parameters:

suffix – filename extension

Yields:

The path of the temporary file.

cedalion.typing module

Type aliases for Cedalion dataclasses.

Cedalion relies as much as possible on generic data types (like xarray DataArrays). We then use type aliases and annotations to augment these data types with additional information about the data they carry. For DataArrays there is a basic mechanism to specify and validate data schemas that specify dimension and coordinate names. This way we can distinguish between time series DataArrays (NDTimeSeries) and DataArrays representing points in space (LabeledPoints). By using these aliases in type hints we indicate to user which kind of DataArray is expected.

Parameters with physical units are represented by cedalion.Quantity. Aliases are defined to indicate the dimensionality of quantities.

cedalion.typing.LabeledPoints[source]

DataArrays representing labeled points in space.

alias of Annotated[DataArray, DataArraySchema(dims=(‘label’,), coords=((‘label’, (‘label’, ‘type’)),))]

cedalion.typing.NDTimeSeries[source]

DataArrays representing time series.

alias of Annotated[DataArray, DataArraySchema(dims=(‘time’,), coords=((‘time’, (‘time’, ‘samples’)),))]

cedalion.typing.AffineTransform[source]

4x4 DataArrays representing affine transformations.

cedalion.typing.QTime[source]

Quantities with units of time

alias of Annotated[Quantity, ‘[time]’]

cedalion.typing.QLength[source]

Quantities with units of length

alias of Annotated[Quantity, ‘[length]’]

cedalion.typing.QFrequency[source]

Quantities with units of frequency

alias of Annotated[Quantity, ‘[frequency]’]

cedalion.typing.QConcentration[source]

Quantities with units of concentration

alias of Annotated[Quantity, ‘[concentration]’]

cedalion.utils module

Utility functions.

cedalion.utils.zero_padded_numbers(numbers: list[int], prefix: str = '') → list[str][source]

Translate [0,1,..,13] to [“00”,”01”, … “13”].

Determine the length of the zero padding to accomodate the highest absolute number. Optionally, a prefix can be specified.

cedalion.utils.deprecated_api(message)[source]

Issue a deprecation warning.

cedalion.utils.deprecated(reason: str)[source]

Marks a function as deprecated by issuing a DeprecationWarning when used.

cedalion.validators module

Validators for common data structures.

cedalion.validators.has_time(array: DataArray)[source]
cedalion.validators.has_wavelengths(array: DataArray)[source]
cedalion.validators.has_channel(array: DataArray)[source]
cedalion.validators.has_positions(array: DataArray, npos: int | None = None)[source]
cedalion.validators.is_quantified(array: DataArray)[source]
cedalion.validators.check_dimensionality(name: str, q: Quantity, dim: str)[source]

cedalion.vtktutils module

cedalion.vtktutils.trimesh_to_vtk_polydata(mesh: Trimesh)[source]

Convert a Trimesh object to a VTK PolyData object.

Parameters:

mesh (trimesh.Trimesh) – The input trimesh object.

Returns:

The converted VTK PolyData object.

Return type:

vtk.vtkPolyData

cedalion.vtktutils.pyvista_polydata_to_trimesh(
polydata: PolyData,
) → Trimesh[source]

Convert a PyVista PolyData object to a Trimesh object.

Parameters:

polydata (pv.PolyData) – The input PyVista PolyData object.

Returns:

The converted Trimesh object.

Return type:

trimesh.Trimesh

cedalion.xrutils module

Utility functions for xarray objects.

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.

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 the dims in a to match the ordering in target.

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 DataArray and sparse array along one dimension.

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

Check the dimensionality of quantified and dequantified DataArrays.

Module contents