Data structures and I/O

Cedalion builds on the scientific Python stack — numpy, xarray, pandas — and adds domain-specific data structures for fNIRS that carry measurement metadata (optode labels, wavelengths, physical units) alongside the numerical values.

The three core types are:

• NDTimeSeries — an xr.DataArray with a time dimension and a spatial dimension. The spatial dimension is channel for raw and channel-space data (with sub-coordinates source and detector that enable joins with the optode geometry), vertex for image-space data on a surface mesh, or parcel for region-level summaries. Physical units (V, mol/L, etc.) are attached via pint-xarray and preserved through transformations.

• LabeledPoints — an xr.DataArray with dimensions (label, <crs>) mapping optode and landmark names to 3-D positions in a named coordinate reference system.

• Recording — a container whose structure closely mirrors the SNIRF file format and serves as the main analysis object. Reading a SNIRF file populates .timeseries (keyed by canonical names such as "amp", "od", "conc"), .geo3d (probe geometry), .stim (stimulus table), .aux_ts (auxiliary time series), and .meta_data; CW, FD, and TD data are all supported per the SNIRF specification. Fields such as .head_model, .masks, and image-space time series extend beyond what SNIRF currently specifies.

For a conceptual introduction with worked examples see the Concepts guide. For a hands-on introduction to these types start with the example notebooks below.

Data structures

cedalion.dataclasses	Data classes used throughout cedalion.
cedalion.typing	Type aliases for Cedalion dataclasses.
cedalion.validators	Validators for common data structures.
cedalion.physunits	Builds on pint_xarray's unit registry.

Utilities

cedalion.xrutils

Utility functions for xarray objects.

I/O

cedalion.io.snirf	Contains functionality for handling .snirf files.
cedalion.io.anatomy	Functions for reading and processing anatomical data.
cedalion.io.bids	Utilities for converting fNIRS datasets to the BIDS standard.
cedalion.io.forward_model	Module for saving and loading forward model computation results.
cedalion.io.photogrammetry	Module for reading photogrammetry output file formats.
cedalion.io.probe_geometry	Module for reading and writing probe geometry files.
cedalion.data	Cedalion datasets and utility functions.

Examples

Xarray Data Structures - an fNIRS example

The Recording Container: Cedalion’s main data structure and a guide to indexing

Loading and Inspecting fNIRS Recordings

Data Structures and I/O

Convert a fNIRS dataset to BIDS

Storing estimated HRFs in snirf files