cedalion.io.snirf

Contains functionality for handling .snirf files.

Functions

`add_number_to_name`(name, keys)	Changes name to name_<number>.
`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_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])	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[, names, module, qualname, ...])
`DataTypeLabel`(value[, names, module, ...])

class cedalion.io.snirf.DataType( value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None, )[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, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None, )[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]

cedalion.io.snirf.parse_data_type(value)[source]

cedalion.io.snirf.parse_data_type_label(value)[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: dict[str, Any], ) → 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 (dict[str, Any]) –
Options for reading the aux data. The following options are supported: - squeeze_aux (bool): If True, squeeze the aux data to remove

dimensions of size 1.

Returns:

Dictionary containing the aux data

Return type:

result (OrderedDict[str, xr.DataArray])

cedalion.io.snirf.add_number_to_name(name, keys)[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, ) → list[tuple[str, 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.

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, opts)[source]

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

Parameters:

nirs_element (NirsElement) – Nirs data element as specified in the snirf documentation (Tucker et al. [TDK+22]).
opts (dict[str, Any]) –
Options for reading the data element. The following options are supported: - squeeze_aux (bool): If True, squeeze the aux data to remove

dimensions of size 1.
- crs (str): name of the geo?d’s coordinate reference system.

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, ) → 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.

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.