cedalion.io.snirf
Contains functionality for handling .snirf files.
Functions
|
Changes name to name_<number>. |
|
Define groupings of data_type, data_type_label and data_type_index. |
|
Enriches measurement list DataFrame with additional information. |
|
Extract 3D coordinates of optodes and landmarks from probe information. |
|
Extract 3D coordinates of optodes and landmarks from a nirs probe variable. |
|
Create a measurement list from a stacked array. |
|
Converts a snirf MeasurementList object to a pandas DataFrame. |
|
Converts the metaDataTags of a nirs element to a dictionary. |
|
|
|
|
|
|
|
Reads the aux data from a nirs element into a dictionary of DataArrays. |
|
Reads the data elements from a nirs element into a list of DataArrays. |
|
Reads a single nirs element from a .snirf file into a Recording object. |
|
Reads a .snirf file into a list of Recording objects. |
|
Deal with multidimensional source labels. |
|
Converts a snirf Stim object to a pandas DataFrame. |
|
Write one or more recordings to a .snirf file. |
Classes
|
|
|
- cedalion.io.snirf.assign_data_type_group(
- data_type: DataType,
- data_type_label: DataTypeLabel,
- data_type_index: int,
- nirs_element: NirsElement,
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_label(value) DataTypeLabel | 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,
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,
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],
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,
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,
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,
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