cedalion.io package
Submodules
cedalion.io.anatomy module
Functions for reading and processing anatomical data.
- cedalion.io.anatomy.read_segmentation_masks(
- basedir: str,
- mask_files: Dict[str, str] = {'csf': 'csf.nii', 'gm': 'gm.nii', 'scalp': 'scalp.nii', 'skull': 'skull.nii', 'wm': 'wm.nii'},
Read segmentation masks from NIFTI files.
- Parameters:
basedir (str) – Directory containing the mask files
mask_files (Dict[str, str]) – Dictionary mapping segmentation types to filenames
- Returns:
masks (xr.DataArray): Concatenated segmentation masks with a new dimension segmentation_type.
affine (np.ndarray): Affine transformation matrix associated with the NIFTI files.
- Return type:
Tuple[xr.DataArray, np.ndarray]
- cedalion.io.anatomy.cell_coordinates(mask, affine, units='mm')[source]
Get the coordinates of each voxel in the transformed mask.
- Parameters:
mask (xr.DataArray) – A binary mask of shape (i, j, k).
affine (np.ndarray) – Affine transformation matrix.
units (str) – Units of the output coordinates.
- Returns:
Coordinates of the center of each voxel in the mask.
- Return type:
xr.DataArray
cedalion.io.bids module
Functions for reading BIDS data.
cedalion.io.forward_model module
Module for saving and loading forward model computation results.
- cedalion.io.forward_model.save_Adot(fn: str, Adot: DataArray)[source]
Save Adot to a netCDF file.
- Parameters:
fn (str) – File name to save the data to.
Adot (xr.DataArray) – Data to save.
- Returns:
None
- cedalion.io.forward_model.load_Adot(fn: str)[source]
Load Adot from a netCDF file.
- Parameters:
fn (str) – File name to load the data from.
- Returns:
Data loaded from the file.
- Return type:
xr.DataArray
cedalion.io.nirs module
cedalion.io.photogrammetry module
Module for reading photogrammetry output file formats.
- cedalion.io.photogrammetry.read_photogrammetry_einstar(fn)[source]
Read optodes and fiducials from photogrammetry pipeline.
This method reads the output file as returned by the photogrammetry pipeline using an einstar device.
- Parameters:
fn (str) – The filename of the einstar photogrammetry output file.
- Returns:
- A tuple containing:
- fiducials (cedalion.LabeledPoints): The fiducials as a cedalion
LabeledPoints object.
- optodes (cedalion.LabeledPoints): The optodes as a cedalion LabeledPoints
object.
- Return type:
tuple
- cedalion.io.photogrammetry.read_einstar(fn)[source]
Read optodes and fiducials from einstar devices.
- Parameters:
fn (str) – The filename of the einstar photogrammetry output file.
- Returns:
- A tuple containing:
fiducials (OrderedDict): The fiducials as an OrderedDict.
optodes (OrderedDict): The optodes as an OrderedDict.
- Return type:
tuple
- cedalion.io.photogrammetry.opt_fid_to_xr(fiducials, optodes)[source]
Convert OrderedDicts fiducials and optodes to cedalion LabeledPoints objects.
- Parameters:
fiducials (OrderedDict) – The fiducials as an OrderedDict.
optodes (OrderedDict) – The optodes as an OrderedDict.
- Returns:
- A tuple containing:
- fiducials (cedalion.LabeledPoints): The fiducials as a cedalion
LabeledPoints object.
- optodes (cedalion.LabeledPoints): The optodes as a cedalion LabeledPoints
object.
- Return type:
tuple
cedalion.io.probe_geometry module
Module for reading and writing probe geometry files.
- cedalion.io.probe_geometry.load_tsv(
- tsv_fname: str,
- crs: str = 'digitized',
- units: str = 'mm',
Load a tsv file containing optodes or landmarks.
- Parameters:
tsv_fname (str) – Path to the tsv file.
crs (str) – Coordinate reference system of the points.
units (str)
Returns
-------
xr.DataArray – Optodes or landmarks as a Data
- cedalion.io.probe_geometry.read_mrk_json(fname: str, crs: str) DataArray[source]
Read a JSON file containing landmarks.
- Parameters:
fname (str) – Path to the JSON file.
crs (str) – Coordinate reference system of the landmarks.
Returns
-------
xr.DataArray – Landmarks as a DataArray.
- cedalion.io.probe_geometry.save_mrk_json(fname: str, landmarks: DataArray, crs: str)[source]
Save landmarks to a JSON file.
- Parameters:
fname (str) – Path to the output file.
landmarks (xr.DataArray) – Landmarks to save.
crs (str) – Coordinate system of the landmarks.
- cedalion.io.probe_geometry.read_digpts(fname: str, units: str = 'mm') DataArray[source]
Read a file containing digitized points.
- Parameters:
fname (str) – Path to the file.
units (str) – Units of the points.
Returns
-------
xr.DataArray – Digitized points as a DataArray.
- cedalion.io.probe_geometry.read_einstar_obj(fname: str) TrimeshSurface[source]
Read a textured triangle mesh generated by Einstar devices.
- Parameters:
fname (str) – Path to the file.
Returns
-------
TrimeshSurface – Triangle
cedalion.io.snirf module
Contains functionality for handling .snirf files.
- class cedalion.io.snirf.DataType(
- value,
- names=None,
- *,
- module=None,
- qualname=None,
- type=None,
- start=1,
- boundary=None,
Bases:
Enum
- class cedalion.io.snirf.DataTypeLabel(
- value,
- names=None,
- *,
- module=None,
- qualname=None,
- type=None,
- start=1,
- boundary=None,
Bases:
StrEnum
- 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