Rationale and Design Goals

Why Cedalion?

The fNIRS community has built a rich ecosystem of analysis toolboxes, largely in MATLAB. Cedalion complements these tools from a different starting point: what would an fNIRS toolbox look like if it were designed from the ground up around the best practices of modern scientific Python — labeled arrays, physical units, composable pipelines, and native integration with machine learning libraries?

The motivation comes in part from a growing demand for analyses that span the full pipeline in a single scriptable environment, and from the expansion of fNIRS into naturalistic, everyday settings. Wearable and mobile systems generate large, heterogeneous datasets that benefit from rigorous data-driven quality control and flexible preprocessing that can adapt to variable recording conditions.

Our view of what constitutes a good answer drives three design goals.

1. Labels and units travel with the data

A recurring source of bugs and misinterpretations in signal processing is the loss of metadata: a numpy array arrives at a function and nobody knows which axis is time, which is channel, or what the values’ physical units are. Cedalion uses xarray DataArrays as its primary data container. Every array carries named dimensions (channel, wavelength, time, …), coordinate labels, and — via pint-xarray — physical units. Operations that would silently drop this context raise an error instead, turning a class of latent bugs into immediate, informative failures.

2. Pipelines are composable and inspectable

Cedalion separates the data model from the processing steps. The Recording container holds all data objects (timeseries, masks, probe geometry, stimulus table, head model) in named dictionaries. Processing functions are ordinary Python callables that take and return arrays or update a Recording in-place. There are no hidden pipeline objects, global state, or implicit parameter inheritance: every step is a regular function call whose inputs and outputs can be inspected, plotted, or serialised at any point.

3. Open standards, reproducibility, and the FAIR principles

Raw data is read and written in SNIRF format, and datasets can be organised as BIDS-compliant archives, making recordings Findable, Accessible, Interoperable, and Reusable (FAIR). Cedalion aims to integrate with MNE Raw to leverage MNE’s extensive EEG and MEG processing routines without leaving the Python ecosystem. scikit-learn estimators accept Cedalion DataArrays directly, behaving like numpy arrays while preserving coordinate metadata. This means you can enter and exit the toolbox at any stage of an analysis, and entire pipelines — from raw data to statistical results — can be shared as self-contained, runnable notebooks.

Target audience

Cedalion is aimed at researchers who:

  • want to write analysis code that is readable, reproducible, and shareable;

  • are comfortable with Python and the scientific stack (numpy, matplotlib, pandas) but do not want to re-implement standard fNIRS building blocks;

  • need capabilities that span the full pipeline — from raw data to image reconstruction and machine learning — without switching tools;

  • work with naturalistic or mobile recordings where data quality is variable and rigorous quality control is essential.

Relation to other toolboxes

The MATLAB-based toolboxes listed below represent the most widely used prior work. Cedalion is not a replacement for any of them; it fills a gap for Python-first workflows that combine multi-step preprocessing, rigorous quality control, DOT image reconstruction, and data-driven methods in a single, scriptable environment.

Toolbox

Primary focus

Language

Homer2 / Homer3

Preprocessing, GLM

MATLAB

AtlasViewer

3D probe registration, DOT

MATLAB

Brain AnalyzIR

Statistical inference, GLM

MATLAB

NeuroDOT

Preprocessing, GLM, DOT image reconstruction

MATLAB

NIRStorm

Multi-modal source imaging

MATLAB

MNE-NIRS

SNIRF I/O, MNE integration

Python

Cedalion

Full pipeline, DOT, data-driven ML

Python

Community and reproducibility

Cedalion is developed as a community resource. Each processing function is linked to its source publication so that algorithm choices are traceable to the primary literature. New contributions are reviewed on GitHub and follow FAIR (Findable, Accessible, Interoperable, Reusable) data principles.

Project status

Cedalion is developed openly at the IBS Lab, TU Berlin in collaboration with Boston University and released under the MIT licence. The project website is www.cedalion.tools.

Contributions are welcome — see the contributing guide. If you use Cedalion in published work, please cite:

Middell, E., Carlton, L., Moradi, S., Codina, T., Fischer, T., Cutler, J., Kelley, S., Behrendt, J., Dissanayake, T., Harmening, N., Yücel, M. A., Boas, D. A., & von Lühmann, A. (2026). Cedalion Tutorial: A Python-based framework for comprehensive analysis of multimodal fNIRS & DOT from the lab to the everyday world (Version 1). arXiv. https://doi.org/10.48550/ARXIV.2601.05923