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, ...)	Map a (data_type, data_type_label, data_type_index) triple to a group string.
compress_snirf(input, output[, compression, ...])	Copy a SNIRF file with HDF5 compression applied where possible.
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 a raw measurement-list data-type value into a DataType enum.
parse_data_type_index(value)	Parse a raw measurement-list data-type index to an integer.
parse_data_type_label(value)	Parse a raw measurement-list data-type label into a DataTypeLabel.
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)	SNIRF data type codes as defined in the SNIRF specification.
DataTypeLabel(value)	SNIRF data type label strings as defined in the SNIRF specification.
ReadSnirfOptions(squeeze_aux, crs, time_units)	Helper class to pass options through read_snirf subroutines.

class cedalion.io.snirf.DataType(value)

Bases: Enum

SNIRF data type codes as defined in the SNIRF specification.

CW_AMPLITUDE = 1

CW_FLUORESCENCE_AMPLITUDE = 51

FD_AC_AMPLITUDE = 101

FD_PHASE = 102

FD_FLUORESCENCE_AMPLITUDE = 151

FD_FLUORESCENCE_PHASE = 152

TDG_AMPLITUDE = 201

TDG_FLUORESCENCE_AMPLITUDE = 251

TDM_AMPLITUDE = 301

TDM_FLUORESCENCE_AMPLITUDE = 351

DCS_G2 = 401

DCS_BFI = 410

PROCESSED = 99999

class cedalion.io.snirf.DataTypeLabel(value)

Bases: StrEnum

SNIRF data type label strings as defined in the SNIRF specification.

DOD = 'dOD'

DMEAN = 'dMean'

DVAR = 'dVar'

DSKEW = 'dSkew'

MUA = 'mua'

MUSP = 'musp'

HBO = 'HbO'

HBR = 'HbR'

HBT = 'HbT'

H2O = 'H2O'

LIPID = 'Lipid'

BFI = 'BFi'

HRF_DOD = 'HRF dOD'

HRF_DMEAN = 'HRF dMean'

HRF_DVAR = 'HRF dVar'

HRF_DSKEW = 'HRF dSkew'

HRF_HBO = 'HRF HbO'

HRF_HBR = 'HRF HbR'

HRF_HBT = 'HRF HbT'

HRF_BFI = 'HRF BFi'

RAW_SATORI = 'RAW'

RAW_NIRX = 'raw-DC'

MOMENTS_KERNEL = 'Time Domain - Moments - Amplitude'

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

Bases: object

Helper class to pass options through read_snirf subroutines.

squeeze_aux

If True, squeeze the aux data to remove dimensions of size 1.

Type:

bool

crs

Name of the geo3D coordinate reference system.

Type:

str | None

time_units

If provided, overrides the time coordinate units read from the file’s metaDataTags.

Type:

str | None

squeeze_aux: bool

crs: str | None

time_units: str | None

cedalion.io.snirf.assign_data_type_group(

data_type: DataType,

data_type_label: DataTypeLabel,

data_type_index: int,

nirs_element: NirsElement,

) → str

Map a (data_type, data_type_label, data_type_index) triple to a group string.

The SNIRF standard allows different data types to share the same data element (e.g. Satori stores processing results this way; Kernel stores temporal moments in one element). Content must be grouped before being packaged into separate DataArrays. This function maps each measurement-list row to a canonical group label used as a key in CANONICAL_NAMES.

Parameters:

• data_type – Parsed DataType enum value.

• data_type_label – Parsed DataTypeLabel enum value (may be None).

• data_type_index – Integer index from the measurement list (may be None).

• nirs_element – The enclosing NIRS element; used to resolve moment orders for Kernel-style TD data.

Returns:

A group label string such as "unprocessed raw" or "processed concentrations".

Raises:

ValueError – If the combination of arguments is not recognised.

cedalion.io.snirf.parse_data_type(value) → DataType | None

Parse a raw measurement-list data-type value into a DataType enum.

Parameters:

value – Raw integer value from the SNIRF measurement list (or None).

Returns:

Corresponding DataType member, or None if value is None or not recognised (a warning is logged in that case).

cedalion.io.snirf.parse_data_type_label(value) → DataTypeLabel | None

Parse a raw measurement-list data-type label into a DataTypeLabel.

Parameters:

value – Raw string value from the SNIRF measurement list (or None).

Returns:

Corresponding DataTypeLabel member, or None if value is None or not recognised (a warning is logged in that case).

cedalion.io.snirf.parse_data_type_index(value) → int | None

Parse a raw measurement-list data-type index to an integer.

Parameters:

value – Raw value from the SNIRF measurement list (or None).

Returns:

Integer index, or None if value is None.

cedalion.io.snirf.reduce_ndim_sourceLabels(sourceLabels: ndarray) → list

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)

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)

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

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]

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)

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]

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])

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')]]

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,

)

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]

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,

)

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,

)

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],

)

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.

cedalion.io.snirf.compress_snirf(

input: Path | str,

output: Path | str,

compression='gzip',

compression_opts=6,

chunks=True,

shuffle=True,

)

Copy a SNIRF file with HDF5 compression applied where possible.

Parameters:

• input – Path to the source SNIRF file.

• output – Path for the compressed output file.

• compression – HDF5 compression filter name (default "gzip").

• compression_opts – Compression level; for gzip this is 0–9 (default 6).

• chunks – Enable HDF5 chunked storage, required for compression (default True).

• shuffle – Apply the byte-shuffle filter before compression to improve ratio (default True).