cedalion package

Subpackages

Submodules

cedalion.datasets module

Cedalion datasets and utility functions.

cedalion.datasets.get_colin27_headmodel()
cedalion.datasets.get_colin27_segmentation(downsampled=False)
cedalion.datasets.get_fingertapping()

Retrieves a finger tapping recording in BIDS format.

Data is from Luke and McAlpine [LM21]

Return type:

Recording

cedalion.datasets.get_fingertapping_snirf_path()
Return type:

Path

cedalion.datasets.get_imagereco_example_fluence()
Return type:

tuple[DataArray, DataArray]

cedalion.datasets.get_multisubject_fingertapping_path()
Return type:

Path

cedalion.datasets.get_multisubject_fingertapping_snirf_paths()
cedalion.datasets.get_photogrammetry_example_scan()
cedalion.datasets.get_snirf_test_data()

cedalion.nirs module

cedalion.nirs.beer_lambert(amplitudes, geo3d, dpf, spectrum='prahl')

Calculate concentration changes from amplitude using the modified BL law.

Parameters:

  • amplitudes (xr.DataArray, (channel, wavelength, *)) – The input data array containing the raw intensities.

  • geo3d (xr.DataArray) – The 3D coordinates of the optodes.

  • dpf (xr.DataArray, (wavelength,*)) – The differential pathlength factors

  • spectrum (str, optional) – The type of spectrum to use for calculating extinction coefficients. Defaults to “prahl”.

Returns:

A data array containing

concentration changes according to the mBLL.

Return type:

conc (xr.DataArray, (channel, *))

cedalion.nirs.channel_distances(amplitudes, geo3d)

Calculate distances between channels.

Parameters:

  • amplitudes (xr.DataArray) – A DataArray representing the amplitudes with dimensions (channel, *).

  • geo3d (xr.DataArray) – A DataArray containing the 3D coordinates of the channels with dimensions (channel, pos).

Returns:

A DataArray containing the calculated distances between

source and detector channels. The resulting DataArray has the dimension ‘channel’.

Return type:

dists (xr.DataArray)

cedalion.nirs.get_extinction_coefficients(spectrum, wavelengths)

Provide a matrix of extinction coefficients from tabulated data.

Parameters:

  • spectrum (str) –

    The type of spectrum to use. Currently supported options are: - “prahl”: Extinction coefficients based on the Prahl absorption spectrum

    (Prahl1998).

  • wavelengths (Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]) – An array-like object containing the wavelengths at which to calculate the extinction coefficients.

Returns:

A matrix of extinction coefficients with dimensions “chromo”

(chromophore, e.g. HbO/HbR) and “wavelength” (e.g. 750, 850, …) at which the coefficients for each chromophore are given in units of “mm^-1 / M”.

Return type:

xr.DataArray

References

(Prahl 1998) - taken from Homer2/3, Copyright 2004 - 2006 - The General Hospital

Corporation and President and Fellows of Harvard University. “These values for the molar extinction coefficient e in [cm-1/(moles/liter)] were compiled by Scott Prahl (prahl@ece.ogi.edu) using data from W. B. Gratzer, Med. Res. Council Labs, Holly Hill, London N. Kollias, Wellman Laboratories, Harvard Medical School, Boston To convert this data to absorbance A, multiply by the molar concentration and the pathlength. For example, if x is the number of grams per liter and a 1 cm cuvette is being used, then the absorbance is given by (e) [(1/cm)/(moles/liter)] (x) [g/liter] (1) [cm] A = —————————————————

66,500 [g/mole]

using 66,500 as the gram molecular weight of hemoglobin. To convert this data to absorption coefficient in (cm-1), multiply by the molar concentration and 2.303, µa = (2.303) e (x g/liter)/(66,500 g Hb/mole) where x is the number of grams per liter. A typical value of x for whole blood is x=150 g Hb/liter.”

cedalion.nirs.int2od(amplitudes)

Calculate optical density from intensity amplitude data.

Parameters:

amplitudes (xr.DataArray, (time, channel, *)) – amplitude data.

Returns:

(xr.DataArray, (time, channel,*): The optical density data.

Return type:

od

cedalion.nirs.od2conc(od, geo3d, dpf, spectrum='prahl')

Calculate concentration changes from optical density data.

Parameters:

  • od (xr.DataArray, (channel, wavelength, *)) – The optical density data array

  • geo3d (xr.DataArray) – The 3D coordinates of the optodes.

  • dpf (xr.DataArray, (wavelength, *)) – The differential pathlength factor data

  • spectrum (str, optional) – The type of spectrum to use for calculating extinction coefficients. Defaults to “prahl”.

Returns:

A data array containing

concentration changes by channel.

Return type:

conc (xr.DataArray, (channel, *))

cedalion.nirs.split_long_short_channels(ts, geo3d, distance_threshold=<Quantity(1.5, 'centimeter')>)

Split a time series into two based on channel distances.

Parameters:

  • ts (DataArray) – FIXME

  • geo3d (DataArray) – FIXME

  • distance_threshold (Quantity) – FIXME

Returns:

time series with channel distances >= distance_threshold ts_short : time series with channel distances < distance_threshold

Return type:

ts_long

cedalion.physunits module

cedalion.plots module

class cedalion.plots.OptodeSelector(surface, points, normals=None, plotter=None, labels=None)

Bases: object

A class for visualizing point clouds with interactive features in PyVista.

This class provides functionality to visualize and interact with labeled point clouds using a PyVista plotter. It allows points to be dynamically added or removed by picking them directly from the plot interface.

surface

The surface of a head for normals.

Type:

cdc.Surface

points

The point cloud data containing point coordinates.

Type:

cdt.LabeledPointCloud

normals

Normal vectors to the points.

Type:

xr.DataArray

plotter

A PyVista plotter instance for rendering the point cloud.

Type:

pv.Plotter

labels

Labels corresponding to the points, displayed if provided.

Type:

list of str, optional

actors

List of PyVista actor objects representing the points in the visualization.

Type:

list

color

Default color for points if not specified by point type.

Type:

str or tuple, optional

plot()

Renders the point cloud using the current settings.

on_pick(picked_point)

Callback function for picking points in the visualization.

update_visualization()

Clears the existing plot and re-renders the point cloud.

enable_picking()

Enables interactive picking of points on the plot.

enable_picking()
find_surface_normal(picked_point, radius=6)
on_pick(picked_point)
plot()
update_normals(normal_at_picked_point, label)
update_visualization()
cedalion.plots.plot3d(brain_mesh, scalp_mesh, geo3d, timeseries, poly_lines=[], brain_scalars=None, plotter=None)

Plots a 3D visualization of brain and scalp meshes.

Parameters:

  • brain_mesh (TrimeshSurface) – The brain mesh as a TrimeshSurface object.

  • scalp_mesh (TrimeshSurface) – The scalp mesh as a TrimeshSurface object.

  • geo3d (xarray.Dataset) – Dataset containing 3-dimentional point centers.

  • timeseries

  • poly_lines

  • brain_scalars

  • plotter (pv.Plotter, optional) – An existing PyVista plotter instance to use for plotting. If None, a new PyVista plotter instance is created. Default is None.

cedalion.plots.plot_labeled_points(plotter, points, color=None, show_labels=False, ppoints=None, labels=None)

Plots a labeled point cloud in a PyVista plotter with optional interaction for picking points.

This function visualizes a point cloud where each point can have a label. Points can be interactively picked if enabled. Picked point is indicated by increased radius.

Parameters:

  • plotter (pv.Plotter) – A PyVista plotter instance used for rendering the points.

  • points (cdt.LabeledPointCloud) – A labeled point cloud data structure containing points and optional labels.

  • color (str or tuple, optional) – Override color for all points. If None, colors are assigned based on point types.

  • show_labels (bool) – If True, labels are displayed next to the points. Default is False.

  • ppoints (list, optional) – A list to store indices of picked points, enables picking if not None. Default is None.

  • labels (list of str, optional) – List of labels to show if show_labels is True. If None and show_labels is True, the labels from points are used.

cedalion.plots.plot_montage3D(amp, geo3d)
cedalion.plots.plot_surface(plotter, surface, color=None, opacity=1.0, pick_landmarks=False, **kwargs)

Plots a surface mesh with optional landmark picking in a PyVista plotter.

Parameters:

  • plotter (pv.Plotter) – A PyVista plotter instance used for rendering the surface.

  • surface (cdc.Surface) – The surface object to be plotted.

  • color (str or tuple, optional) – Color of the mesh.

  • opacity (float) – Opacity of the mesh, ranging from 0 (transparent) to 1 (opaque). Default is 1.0.

  • pick_landmarks (bool) – If True, enables interactive picking of landmarks on the surface. Default is False.

Returns:

If pick_landmarks is True, returns a function that when called, provides the current picked points and their labels. This function prints warnings if some labels are missing or are repeated.

Return type:

function

cedalion.plots.plot_vector_field(plotter, points, vectors, ppoints=None)
cedalion.plots.scalp_plot(recording, metric, ax, colormap=<matplotlib.colors.LinearSegmentedColormap object>, title=None, threshold_ind=None, threshold_col=None, saturation=None, vmin=0, vmax=1, savePath=None, remove_short=0, flagFontSize=0, flagMarkerSize=8)

CREATE A 2D MONTAGE OF OPTODES WITH CHANNELS COLOURED ACCORDING TO A GIVEN METRIC

Parameters:

  • information (geo3d -> probe)

  • montage (ax -> axis object to plot the)

  • channels (colormap -> colormap to use to color the)

  • channels

  • plot (title -> title for the)

  • lines (threshold -> metrics values below threshold will be plotted as dotted)

  • colorbar (vmax -> maximum value for the)

  • colorbar

cedalion.tasks module

cedalion.tasks.task(f)

cedalion.typing module

cedalion.validators module

cedalion.validators.check_dimensionality(name, q, dim)
cedalion.validators.has_channel(array)
cedalion.validators.has_positions(array, npos=None)
cedalion.validators.has_time(array)
cedalion.validators.has_wavelengths(array)
cedalion.validators.is_quantified(array)

cedalion.vtktutils module

cedalion.vtktutils.pyvista_polydata_to_trimesh(polydata)
Return type:

Trimesh

cedalion.vtktutils.trimesh_to_vtk_polydata(mesh)

cedalion.xrutils module

Utility functions for xarray objects.

cedalion.xrutils.apply_mask(data_array, mask, operator, dim_collapse)

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

Parameters:

  • data_array (DataArray) – NDTimeSeries, input time series data xarray

  • mask (DataArray) – input boolean mask array with a subset of dimensions matching data_array

  • operator (str) – 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 (str) – 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, kernel, dim)

Convolve a DataArray along a given dimension “dim” with a “kernel”.

Return type:

DataArray

cedalion.xrutils.mask(array, initval)

Create a boolean mask array with the same shape as the input array.

Return type:

DataArray

cedalion.xrutils.norm(array, dim)

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.other_dim(data_array, *dims)

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 (DataArray) – a xr.DataArray

  • *dims (str) – names of dimensions

Return type:

str

Returns:

The name of the dimension of data_array.

cedalion.xrutils.pinv(array)

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)

Module contents