Cedalion

A Python framework for the data-driven analysis of functional near-infrared spectroscopy (fNIRS) and diffuse optical tomography (DOT) in naturalistic environments. Developed by the Intelligent Biomedical Sensing (IBS) Lab with and for the community.

Note

You are reading the documentation for the latest development version. Use the version switcher (top-left of the page) to select documentation for a specific release that matches your installed package.

What is Cedalion?

Cedalion covers the full fNIRS and DOT analysis pipeline: from raw light intensity through signal quality assessment, preprocessing, and hemodynamic modeling to image reconstruction and statistical inference. It is designed for researchers who want transparent, reproducible, and extensible analysis rather than black-box processing.

The toolbox is built on a modern Python scientific stack — xarray for labeled multi-dimensional arrays, pint for physical unit tracking, and MNE for EEG/fNIRS integration — and is compatible with the SNIRF and BIDS data standards. All data transformations preserve axis labels and physical units by design, making it straightforward to trace results back to their neuroimaging origin.

Quick Start

The following snippet loads a bundled finger-tapping dataset and converts amplitude measurements to haemoglobin concentration in five lines:

import cedalion
import cedalion.nirs.cw as nirs
import xarray as xr

rec = cedalion.data.get_fingertapping()          # load Recording (auto-downloaded)
od  = nirs.int2od(rec["amp"])                    # amplitude → optical density
dpf = xr.DataArray([6.0, 6.0], dims="wavelength",
                   coords={"wavelength": od.wavelength})
conc = nirs.od2conc(od, rec.geo3d, dpf)          # OD → HbO / HbR (µM)

New to Cedalion? Start with the installation guide, then work through the tutorial notebooks. The concepts guide explains the core data model and fNIRS terminology.

You can find the source code on GitHub.

General Info

• Rationale and Design Goals
• Getting started
• Data Structures
• Community

⭐ Tutorial

• Paper (in prep.)
• Tutorial Notebooks

Package Features

• Data structures and I/O
• Signal processing
• Modeling and Machine Learning
• Diffuse optical tomography
• Physiology
• Plotting and Visualization
• Synthetic Data

Reference

• API reference
• Bibliography
• All examples

Project

• Source code
• Issues
• Documentation
• Changelog

Special Thanks

We cordially thank our friends and long-term collaborators at the BOAS Lab for their contributions and support in starting this project.

Version

This documentation was built from commit d732608.