cedalion.dataclasses package

Submodules

cedalion.dataclasses.accessors module

Accessors for Cedalion data types.

class cedalion.dataclasses.accessors.CedalionAccessor(xarray_obj)

Bases: object

Accessor for time series data stored in xarray DataArrays.

property sampling_rate

Return the sampling rate of the time series.

The sampling rate is calculated as the reciprocal of the mean time difference

between consecutive samples.

to_epochs(

df_stim: pd.DataFrame,

trial_types: list[str],

before: cdt.QTime,

after: cdt.QTime,

)

Extract epochs from the time series based on stimulus events.

Parameters:

• df_stim – DataFrame containing stimulus events.

• trial_types – List of trial types to include in the epochs.

• before – Time before stimulus event to include in epoch.

• after – Time after stimulus event to include in epoch.

Returns:

Array containing the extracted epochs.

Return type:

xarray.DataArray

freq_filter(fmin, fmax, butter_order=4)

Applys a Butterworth filter.

Parameters:

• fmin (float) – The lower cutoff frequency.

• fmax (float) – The upper cutoff frequency.

• butter_order (int) – The order of the Butterworth filter.

Returns:

The filtered time series.

Return type:

result (xarray.DataArray)

class cedalion.dataclasses.accessors.PointsAccessor(xarray_obj)

Bases: object

to_homogeneous()

rename(translations: Dict[str, str])

common_labels(

other: DataArray,

) → List[str]

Return labels contained in both LabledPointClouds.

apply_transform(transform: cdt.AffineTransform | np.ndarray)

property crs

set_crs(value: str)

add(

label: str | List[str],

coordinates: ArrayLike,

type: PointType | List[PointType],

group: str | List[str] = None,

) → cdt.LabeledPointCloud

remove(label)

class cedalion.dataclasses.accessors.StimAccessor(pandas_obj)

Bases: object

Accessor for stimulus DataFrames.

rename_events(rename_dict)

Renames trial types in the DataFrame based on the provided dictionary.

Parameters:

rename_dict (dict) – A dictionary with the old trial type as key and the new trial type as value.

conditions()

to_xarray(time: DataArray)

cedalion.dataclasses.geometry module

Dataclasses for representing geometric objects.

class cedalion.dataclasses.geometry.PointType(

value,

names=None,

*,

module=None,

qualname=None,

type=None,

start=1,

boundary=None,

)

Bases: Enum

UNKNOWN = 0

SOURCE = 1

DETECTOR = 2

LANDMARK = 3

class cedalion.dataclasses.geometry.Surface(mesh: Any, crs: str, units: Unit)

Bases: ABC

Abstract base class for surfaces.

mesh: Any

crs: str

units: Unit

abstract property vertices: Annotated[DataArray, DataArraySchema(dims='label', coords='label', 'label', 'type')]

abstract property nvertices: int

abstract property nfaces: int

abstract apply_transform(transform: DataArray)

property kdtree

snap(

points: Annotated[DataArray, DataArraySchema(dims='label', coords='label', 'label', 'type')],

)

Snap points to the nearest vertices on the surface.

class cedalion.dataclasses.geometry.Voxels(voxels: ndarray, crs: str, units: Unit)

Bases: object

3D voxels represented by a np.array.

voxels

The voxels.

Type:

np.ndarray

crs

The coordinate reference system of the voxels.

Type:

str

units

The units of the voxels.

Type:

pint.Unit

voxels: ndarray

crs: str

units: Unit

property vertices: Annotated[DataArray, DataArraySchema(dims='label', coords='label', 'label', 'type')]

property nvertices: int

apply_transform(

transform: DataArray,

) → Voxels

property kdtree

class cedalion.dataclasses.geometry.TrimeshSurface(mesh: Trimesh, crs: str, units: Unit)

Bases: Surface

A surface represented by a trimesh object.

mesh

The trimesh object representing the surface.

Type:

trimesh.Trimesh

crs

The coordinate reference system of the surface.

Type:

str

units

The units of the surface.

Type:

pint.Unit

mesh: Trimesh

property vertices: Annotated[DataArray, DataArraySchema(dims='label', coords='label', 'label', 'type')]

property nvertices: int

property nfaces: int

apply_transform(

transform: DataArray,

) → TrimeshSurface

Apply an affine transformation to this surface.

Parameters:

transform (cdt.AffineTransform) – The affine transformation to apply.

Returns:

The transformed surface.

Return type:

TrimeshSurface

decimate(

face_count: int,

) → TrimeshSurface

Use quadric decimation to reduce the number of vertices.

Parameters:

face_count – the number of faces of the decimated mesh

Returns:

The surface with a decimated mesh

smooth(lamb: float) → TrimeshSurface

Apply a Taubin filter to smooth this surface.

get_vertex_normals(

points: Annotated[DataArray, DataArraySchema(dims='label', coords='label', 'label', 'type')],

normalized=True,

)

Get normals of vertices closest to the provided points.

fix_vertex_normals()

classmethod from_vtksurface(vtk_surface: VTKSurface)

class cedalion.dataclasses.geometry.VTKSurface(

mesh: vtkmodules.vtkCommonDataModel.vtkPolyData,

crs: str,

units: pint.registry.Unit,

)

Bases: Surface

mesh: vtkPolyData

property vertices: Annotated[DataArray, DataArraySchema(dims='label', coords='label', 'label', 'type')]

property nvertices: int

property nfaces: int

apply_transform(transform: DataArray)

classmethod from_trimeshsurface(tri_mesh: TrimeshSurface)

decimate(

reduction: float,

**kwargs,

) → VTKSurface

Use VTK’s decimate_pro method to reduce the number of vertices.

Parameters:

• reduction – Reduction factor. A value of 0.9 will leave 10% of the original number of vertices.

• **kwargs – additional keyword arguments are passed to decimate_pro

Returns:

The surface with a decimated mesh

class cedalion.dataclasses.geometry.SimpleMesh(pts: numpy.ndarray, polys: numpy.ndarray)

Bases: object

pts: ndarray

polys: ndarray

class cedalion.dataclasses.geometry.PycortexSurface(

mesh: SimpleMesh,

crs: str,

units: Unit,

)

Bases: Surface

Provides the geodesic functionality of Pycortex.

References

Functions in this class are based on the implementation in Pycortex (Gao et al. [GHLG15]). Gao JS, Huth AG, Lescroart MD and Gallant JL (2015) Pycortex: an interactive surface visualizer for fMRI. Front. Neuroinform. 9:23. doi: 10.3389/fninf.2015.00023

mesh: SimpleMesh

property vertices: Annotated[DataArray, DataArraySchema(dims='label', coords='label', 'label', 'type')]

property nvertices: int

property nfaces: int

apply_transform(

transform: DataArray,

) → PycortexSurface

decimate(

face_count: int,

) → PycortexSurface

get_vertex_normals(

points: Annotated[DataArray, DataArraySchema(dims='label', coords='label', 'label', 'type')],

normalized=True,

)

property ppts: ndarray

3D matrix of points in each face.

n faces x 3 per face x 3 coords per point.

property connected: csr_matrix

Sparse matrix of vertex-face associations.

property adj: csr_matrix

Sparse vertex adjacency matrix.

property face_normals: ndarray

Normal vector for each face.

property vertex_normals: ndarray

Normal vector for each vertex (average of normals for neighboring faces).

property face_areas: ndarray

Area of each face.

property cotangent_weights: ndarray

Cotangent of angle opposite each vertex in each face.

property laplace_operator

Laplace-Beltrami operator for this surface.

A sparse adjacency matrix with edge weights determined by the cotangents of the angles opposite each edge. Returns a 4-tuple (B, D, W, V) where D is the ‘lumped mass matrix’, W is the weighted adjacency matrix, and V is a diagonal matrix that normalizes the adjacencies. The ‘stiffness matrix’, A, can be computed as V - W.

The full LB operator can be computed as D^{-1} (V - W).

B is the finite element method (FEM) ‘mass matrix’, which replaces D in FEM analyses.

See ‘Discrete Laplace-Beltrami operators for shape analysis and segmentation’ by Reuter et al., 2009 for details.

property avg_edge_length

Average length of all edges in the surface.

surface_gradient(scalars, at_verts=True)

Gradient of a function with values scalars at each vertex on the surface.

If at_verts, returns values at each vertex. Otherwise, returns values at each face.

Parameters:

• scalars – 1D ndarray, shape (total_verts,) a scalar-valued function across the cortex.

• at_verts – bool, optional If True (default), values will be returned for each vertex. Otherwise, values will be returned for each face.

Returns:

2D ndarray, shape (total_verts,3) or (total_polys,3)

Contains the x-, y-, and z-axis gradients of the given scalars at either each vertex (if at_verts is True) or each face.

Return type:

gradu

geodesic_distance(verts, m=1.0, fem=False)

Calcualte the inimum mesh geodesic distance (in mm).

The geodesic distance is calculated from each vertex in surface to any vertex in the collection verts.

Geodesic distance is estimated using heat-based method (see ‘Geodesics in Heat’, Crane et al, 2012). Diffusion of heat along the mesh is simulated and then used to infer geodesic distance. The duration of the simulation is controlled by the parameter m. Larger values of m will smooth & regularize the distance computation. Smaller values of m will roughen and will usually increase error in the distance computation. The default value of 1.0 is probably pretty good.

This function caches some data (sparse LU factorizations of the laplace-beltrami operator and the weighted adjacency matrix), so it will be much faster on subsequent runs.

The time taken by this function is independent of the number of vertices in verts.

Parameters:

• verts – 1D array-like of ints Set of vertices to compute distance from. This function returns the shortest distance to any of these vertices from every vertex in the surface.

• m – float, optional Reverse Euler step length. The optimal value is likely between 0.5 and 1.5. Default is 1.0, which should be fine for most cases.

• fem – bool, optional Whether to use Finite Element Method lumped mass matrix. Wasn’t used in Crane 2012 paper. Doesn’t seem to help any.

Returns:

1D ndarray, shape (total_verts,) Geodesic distance (in mm) from each vertex in the surface to the closest vertex in verts.

geodesic_path(a, b, max_len=1000, d=None, **kwargs)

Finds the shortest path between two points a and b.

This shortest path is based on geodesic distances across the surface. The path starts at point a and selects the neighbor of a in the graph that is closest to b. This is done iteratively with the last vertex in the path until the last point in the path is b.

Other Parameters in kwargs are passed to the geodesic_distance function to alter how geodesic distances are actually measured

Parameters:

• a – int Vertex that is the start of the path

• b – int Vertex that is the end of the path

• d – array array of geodesic distances, will be computed if not provided

• max_len – int, optional, default=1000 Maximum path length before the function quits. Sometimes it can get stuck in loops, causing infinite paths.

• m – float, optional Reverse Euler step length. The optimal value is likely between 0.5 and 1.5. Default is 1.0, which should be fine for most cases.

• fem – bool, optional Whether to use Finite Element Method lumped mass matrix. Wasn’t used in Crane 2012 paper. Doesn’t seem to help any.

• kwargs – other arugments are passed to self.geodesic_distance

Returns:

list

List of the vertices in the path from a to b

Return type:

path

classmethod from_trimeshsurface(

tri_mesh: TrimeshSurface,

)

classmethod from_vtksurface(vtk_surface: VTKSurface)

cedalion.dataclasses.geometry.affine_transform_from_numpy(

transform: ndarray,

from_crs: str,

to_crs: str,

from_units: str,

to_units: str,

) → DataArray

Create a AffineTransform object from a numpy array.

cedalion.dataclasses.recording module

Recording class definition for timeseries data.

class cedalion.dataclasses.recording.Recording(

timeseries: ~collections.OrderedDict[str,

cdt.NDTimeSeries] = <factory>,

masks: ~collections.OrderedDict[str,

~xarray.core.dataarray.DataArray] = <factory>,

geo3d: cdt.LabeledPointCloud = <factory>,

geo2d: cdt.LabeledPointCloud = <factory>,

stim: ~pandas.core.frame.DataFrame = <factory>,

aux_ts: ~collections.OrderedDict[str,

cdt.NDTimeSeries] = <factory>,

aux_obj: ~collections.OrderedDict[str,

~typing.Any] = <factory>,

head_model: ~typing.Any | None = None,

meta_data: ~collections.OrderedDict[str,

~typing.Any] = <factory>,

_measurement_lists: ~collections.OrderedDict[str,

~pandas.core.frame.DataFrame] = <factory>,

)

Bases: object

Main container for analysis objects.

The Recording class holds timeseries adjunct objects in ordered dictionaries. It maps to the NirsElement in the snirf format but it also holds additional attributes (masks, headmodel, aux_obj) for which there is no corresponding entity in the snirf format.

timeseries

A dictionary of timeseries objects. The keys are the names of the timeseries.

Type:

OrderedDict[str, NDTimeSeries]

masks

A dictionary of masks. The keys are the names of the masks.

Type:

OrderedDict[str, xr.DataArray]

geo3d

A labeled point cloud representing the 3D geometry of the recording.

Type:

LabeledPointCloud

geo2d

A labeled point cloud representing the 2D geometry of the recording.

Type:

LabeledPointCloud

stim

A dataframe containing the stimulus information.

Type:

pd.DataFrame

aux_ts

A dictionary of auxiliary timeseries objects.

Type:

OrderedDict[str, NDTimeSeries]

aux_obj

A dictionary of auxiliary objects.

Type:

OrderedDict[str, Any]

head_model

A head model object.

Type:

Optional[Any]

meta_data

A dictionary of meta data.

Type:

OrderedDict[str, Any]

timeseries: OrderedDict[str, NDTimeSeries]

masks: OrderedDict[str, xr.DataArray]

geo3d: LabeledPointCloud

geo2d: LabeledPointCloud

stim: pd.DataFrame

aux_ts: OrderedDict[str, NDTimeSeries]

aux_obj: OrderedDict[str, Any]

head_model: Any | None = None

meta_data: OrderedDict[str, Any]

get_timeseries(key: str | None = None) → cdt.NDTimeSeries

Get a timeseries object by key.

Parameters:

key (Optional[str]) – The key of the timeseries to retrieve. If None, the last timeseries is returned.

Returns:

The requested timeseries object.

Return type:

NDTimeSeries

set_timeseries(key: str, value: cdt.NDTimeSeries, overwrite: bool = False)

get_mask(key: str | None = None) → DataArray

Get a mask by key.

Parameters:

key (Optional[str]) – The key of the mask to retrieve. If None, the last mask is returned.

Returns:

The requested mask.

Return type:

xr.DataArray

set_mask(

key: str,

value: DataArray,

overwrite: bool = False,

)

Set a mask.

Parameters:

• key (str) – The key of the mask to set.

• value (xr.DataArray) – The mask to set.

• overwrite (bool) – Whether to overwrite an existing mask with the same key. Defaults to False.

get_timeseries_type(key)

Get the type of a timeseries.

Parameters:

key (str) – The key of the timeseries.

Returns:

The type of the timeseries.

Return type:

str

property source_labels

Get the unique source labels from the timeseries.

Returns:

A list of unique source labels.

Return type:

list

property detector_labels

Get the unique detector labels from the timeseries.

Returns:

A list of unique detector labels.

Return type:

list

property wavelengths

Get the unique wavelengths from the timeseries.

Returns:

A list of unique wavelengths.

Return type:

list

property trial_types

Get the unique trial types from the stimulus dataframe.

Returns:

A list of unique trial types.

Return type:

list

cedalion.dataclasses.schemas module

Data array schemas and utilities to build labeled data arrays.

exception cedalion.dataclasses.schemas.ValidationError

Bases: Exception

class cedalion.dataclasses.schemas.DataArraySchema(dims: tuple[str], coords: tuple[tuple[str, tuple[str]]])

Bases: object

dims: tuple[str]

coords: tuple[tuple[str, tuple[str]]]

validate(data_array: DataArray)

cedalion.dataclasses.schemas.validate_schemas(func)

cedalion.dataclasses.schemas.build_timeseries(

data: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes],

dims: List[str],

time: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes],

channel: List[str],

value_units: str,

time_units: str,

other_coords: dict[str, _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]] = {},

)

Build a labeled time series data array.

Parameters:

• data (ArrayLike) – The data values.

• dims (List[str]) – The dimension names.

• time (ArrayLike) – The time values.

• channel (List[str]) – The channel names.

• value_units (str) – The units of the data values.

• time_units (str) – The units of the time values.

• other_coords (dict[str, ArrayLike]) – Additional coordinates.

Returns:

The labeled time series data array.

Return type:

da (xr.DataArray)

cedalion.dataclasses.schemas.build_labeled_points(

coordinates: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None,

crs: str = 'pos',

units: Unit | str | None = '1',

labels: list[str] | None = None,

types: list[str] | None = None,

)

Build a labeled point cloud data array.

Parameters:

• coordinates (ArrayLike, optional) – The coordinates of the points. Default: None.

• crs (str, optional) – The coordinate system. Defaults to “pos”.

• units (Optional[pint.Unit | str], optional) – The units of the coordinates. Defaults to “1”.

• labels (Optional[list[str]], optional) – The labels of the points. Defaults to None.

• types (Optional[list[str]], optional) – The types of the points. Defaults to None.

Returns:

The labeled point cloud data array.

Return type:

xr.DataArray

cedalion.dataclasses.schemas.validate_stim_schema(df: DataFrame)

cedalion.dataclasses.schemas.build_stim_dataframe()

Module contents

Data classes used throughout cedalion.