cedalion.io.snirf

Contains functionality for handling .snirf files.

Functions

`add_number_to_name`(name, keys)	Changes name to name_<number>.
`assign_data_type_group`(data_type, ...)	Define groupings of data_type, data_type_label and data_type_index.
`denormalize_measurement_list`(df_ml, nirs_element)	Enriches measurement list DataFrame with additional information.
`geometry_from_probe`(nirs_element, dim, crs)	Extract 3D coordinates of optodes and landmarks from probe information.
`labels_and_positions`(probe[, dim])	Extract 3D coordinates of optodes and landmarks from a nirs probe variable.
`measurement_list_from_stacked`(stacked_array, ...)	Create a measurement list from a stacked array.
`measurement_list_to_dataframe`(measurement_list)	Converts a snirf MeasurementList object to a pandas DataFrame.
`meta_data_tags_to_dict`(nirs_element)	Converts the metaDataTags of a nirs element to a dictionary.
`parse_data_type`(value)
`parse_data_type_index`(value)
`parse_data_type_label`(value)
`read_aux`(nirs_element, opts)	Reads the aux data from a nirs element into a dictionary of DataArrays.
`read_data_elements`(data_element, ...)	Reads the data elements from a nirs element into a list of DataArrays.
`read_nirs_element`(nirs_element, opts)	Reads a single nirs element from a .snirf file into a Recording object.
`read_snirf`(fname[, crs, squeeze_aux, time_units])	Reads a .snirf file into a list of Recording objects.
`reduce_ndim_sourceLabels`(sourceLabels)	Deal with multidimensional source labels.
`stim_to_dataframe`(stim)	Converts a snirf Stim object to a pandas DataFrame.
`write_snirf`(fname, recordings)	Write one or more recordings to a .snirf file.

Classes

`DataType`(value)
`DataTypeLabel`(value)
`ReadSnirfOptions`(squeeze_aux, crs, time_units)	Helper class to pass options through read_snirf subroutines.

class cedalion.io.snirf.DataType(value)[source]

Bases: Enum

CW_AMPLITUDE = 1[source]

CW_FLUORESCENCE_AMPLITUDE = 51[source]

FD_AC_AMPLITUDE = 101[source]

FD_PHASE = 102[source]

FD_FLUORESCENCE_AMPLITUDE = 151[source]

FD_FLUORESCENCE_PHASE = 152[source]

TDG_AMPLITUDE = 201[source]

TDG_FLUORESCENCE_AMPLITUDE = 251[source]

TDM_AMPLITUDE = 301[source]

TDM_FLUORESCENCE_AMPLITUDE = 351[source]

DCS_G2 = 401[source]

DCS_BFI = 410[source]

PROCESSED = 99999[source]

class cedalion.io.snirf.DataTypeLabel(value)[source]

Bases: StrEnum

DOD = 'dOD'[source]

DMEAN = 'dMean'[source]

DVAR = 'dVar'[source]

DSKEW = 'dSkew'[source]

MUA = 'mua'[source]

MUSP = 'musp'[source]

HBO = 'HbO'[source]

HBR = 'HbR'[source]

HBT = 'HbT'[source]

H2O = 'H2O'[source]

LIPID = 'Lipid'[source]

BFI = 'BFi'[source]

HRF_DOD = 'HRF dOD'[source]

HRF_DMEAN = 'HRF dMean'[source]

HRF_DVAR = 'HRF dVar'[source]

HRF_DSKEW = 'HRF dSkew'[source]

HRF_HBO = 'HRF HbO'[source]

HRF_HBR = 'HRF HbR'[source]

HRF_HBT = 'HRF HbT'[source]

HRF_BFI = 'HRF BFi'[source]

RAW_SATORI = 'RAW'[source]

RAW_NIRX = 'raw-DC'[source]

MOMENTS_KERNEL = 'Time Domain - Moments - Amplitude'[source]

class cedalion.io.snirf.ReadSnirfOptions(squeeze_aux: bool, crs: str | None, time_units: str | None)[source]

Bases: object

Helper class to pass options through read_snirf subroutines.

Attrs:: squeeze_aux: If True, squeeze the aux data to remove dimensions of size 1. crs: the name of the geo3D’s coordinate reference system time_units : If provided, this sets the units of the time coordinates.

squeeze_aux: bool[source]

crs: str | None[source]

time_units: str | None[source]

cedalion.io.snirf.assign_data_type_group( data_type: DataType, data_type_label: DataTypeLabel, data_type_index: int, nirs_element: NirsElement, ) → str[source]

Define groupings of data_type, data_type_label and data_type_index.

The snirf standard allows to put different data types into the same data element. Satori does this to store processing results. Kernel stores different moments in the same data element. When reading such data elements, their content must be grouped by data type and the groups will be individually packaged in DataArrays.

To this end, combinations of data_type, data_type_label and data_type_index are mapped to a data_type_group string.

cedalion.io.snirf.parse_data_type(value) → DataType | None[source]

cedalion.io.snirf.parse_data_type_label(value) → DataTypeLabel | None[source]

cedalion.io.snirf.parse_data_type_index(value) → int | None[source]

cedalion.io.snirf.reduce_ndim_sourceLabels(sourceLabels: ndarray) → list[source]

Deal with multidimensional source labels.

snirf supports multidimensional source labels but we don’t. This function tries to reduce n-dimensional source labels to a unique common prefix to obtain only one label per source.

Parameters:: sourceLabels (np.ndarray) – The source labels to reduce.
Returns:: The reduced source labels.
Return type:: list

cedalion.io.snirf.labels_and_positions(probe, dim: int = 3)[source]

Extract 3D coordinates of optodes and landmarks from a nirs probe variable.

Parameters:

probe – Nirs probe geometry variable, see snirf docs (Tucker et al. [TDK+22]).
dim (int) – Must be either 2 or 3.

Returns:

A tuple containing the source, detector, and landmark labels/positions.

Return type:

tuple

cedalion.io.snirf.geometry_from_probe(nirs_element: NirsElement, dim: int, crs: str)[source]

Extract 3D coordinates of optodes and landmarks from probe information.

Parameters:

nirs_element (NirsElement) – Nirs data element as specified in the snirf documentation (Tucker et al. [TDK+22]).
dim (int) – Must be either 2 or 3.
crs – the name of coordinate reference system

Returns:

A DataArray containing the 3D coordinates of optodes and: landmarks, with dimensions ‘label’ and ‘pos’ and coordinates ‘label’ and ‘type’.

Return type:

xr.DataArray

cedalion.io.snirf.measurement_list_to_dataframe( measurement_list: MeasurementList, drop_none: bool = False, ) → DataFrame[source]

Converts a snirf MeasurementList object to a pandas DataFrame.

Parameters:

measurement_list – MeasurementList object from the snirf file.
drop_none (bool) – If True, drop columns that are None for all rows.

Returns:

DataFrame containing the measurement list information.

Return type:

pd.DataFrame

cedalion.io.snirf.meta_data_tags_to_dict( nirs_element: NirsElement, ) → OrderedDict[str, Any][source]

Converts the metaDataTags of a nirs element to a dictionary.

Parameters:: nirs_element (NirsElement) – Nirs data element as specified in the snirf documentation (Tucker et al. [TDK+22]).
Returns:: Dictionary containing the metaDataTags information.
Return type:: OrderedDict[str, Any]

cedalion.io.snirf.stim_to_dataframe(stim: Stim)[source]

Converts a snirf Stim object to a pandas DataFrame.

Parameters:: stim (Stim) – Stim object as specified in the snirf documentation (Tucker et al. [TDK+22]).
Returns:: DataFrame containing the stimulus information.
Return type:: pd.DataFrame

cedalion.io.snirf.read_aux( nirs_element: NirsElement, opts: ReadSnirfOptions, ) → OrderedDict[str, DataArray][source]

Reads the aux data from a nirs element into a dictionary of DataArrays.

Parameters:

nirs_element (NirsElement) – Nirs data element as specified in the snirf documentation (Tucker et al. [TDK+22]).
opts – options passed to read_snirf.

Returns:

Dictionary containing the aux data

Return type:

result (OrderedDict[str, xr.DataArray])

cedalion.io.snirf.add_number_to_name(name: str, keys: list[str])[source]

Changes name to name_<number>.

Number appended to name is the smallest number that makes the new name unique with respect to the list of keys.

Parameters:

name (str) – Name to which a number should be added.
keys (list[str]) – List of keys to which the new name should be compared.

Returns:

New name with number added.

Return type:

str

cedalion.io.snirf.read_data_elements( data_element: DataElement, nirs_element: NirsElement, stim: DataFrame, opts: ReadSnirfOptions, ) → list[tuple[str, TypeAliasForwardRef('cdt.NDTimeSeries')]][source]

Reads the data elements from a nirs element into a list of DataArrays.

Parameters:

data_element (DataElement) – DataElement obj. from the snirf file.
nirs_element (NirsElement) – Nirs data element as specified in the snirf documentation (Tucker et al. [TDK+22]).
stim (pd.DataFrame) – DataFrame containing the stimulus information.
opts – Options passed to read_snirf.

Returns:

List of tuples containing the canonical name: of the data element and the DataArray.

Return type:

list[tuple[str, NDTimeSeries]]

cedalion.io.snirf.read_nirs_element( nirs_element: NirsElement, opts: ReadSnirfOptions, )[source]

Reads a single nirs element from a .snirf file into a Recording object.

Parameters:

nirs_element – Nirs data element as specified in the snirf documentation (Tucker et al. [TDK+22]).
opts – Options passed to read_snirf.

Returns:

Recording object containing the data from the nirs element.

Return type:

rec (Recording)

cedalion.io.snirf.read_snirf( fname: Path | str, crs: str = 'pos', squeeze_aux: bool = False, time_units: str | None = None, ) → list[Recording][source]

Reads a .snirf file into a list of Recording objects.

Parameters:

fname – Path to .snirf file
crs – the name of the geo3D’s coordinate reference system
squeeze_aux – If True, squeeze the aux data to remove dimensions of size 1.
time_units – If provided, this sets the units of the time coordinates. This is useful, when the snirf file specifies time units incorrectly or not at all.

Returns:

List of Recording objects containing the data from the nirs elements in the .snirf file.

Return type:

list[Recording]

cedalion.io.snirf.denormalize_measurement_list( df_ml: DataFrame, nirs_element: NirsElement, )[source]

Enriches measurement list DataFrame with additional information.

Parameters:

df_ml (pd.DataFrame) – DataFrame containing the measurement list information.
nirs_element (NirsElement) – Nirs data element as specified in the snirf documentation (Tucker et al. [TDK+22]).

Returns:

DataFrame containing the measurement list information with: additional columns for channel, source, detector, wavelength and chromo.

Return type:

pd.DataFrame

cedalion.io.snirf.measurement_list_from_stacked( stacked_array, data_type, trial_types, stacked_channel='snirf_channel', source_labels=None, detector_labels=None, wavelengths=None, )[source]

Create a measurement list from a stacked array.

Parameters:

stacked_array (xr.DataArray) – Stacked array containing the data.
data_type (str) – Data type of the data.
trial_types (list[str]) – List of trial types.
stacked_channel (str) – Name of the channel dimension in the stacked array.
source_labels (list[str]) – List of source labels.
detector_labels (list[str]) – List of detector labels.
wavelengths (list[float]) – List of wavelengths.

Returns:

A tuple containing the source labels, detector labels, wavelengths, and: the measurement list.

Return type:

tuple

cedalion.io.snirf.write_snirf( fname: Path | str, recordings: Recording | list[Recording], )[source]

Write one or more recordings to a .snirf file.

Parameters:

fname (Path | str) – Path to .snirf file.
recordings (Recording | list[Recording]) – Recording object(s) to write to the file.