Getting started

This section guides you through installing Cedalion and running your first analysis.

Recommended reading order:

1. Concepts — if you are new to fNIRS, start here to learn the measurement physics and Cedalion’s core data model before writing any code.

2. Installation — set up a conda environment and install the package.

3. Google Colab setup — run example notebooks in the cloud from your browser without a local installation.

4. Quick start — load a recording, compute haemoglobin concentration, and plot a channel in under 20 lines.

5. Tutorial notebooks — seven end-to-end notebooks covering the full pipeline from data loading to image reconstruction.

6. Contributing code — how to add new functions, follow the style guide, and submit a pull request.

• Core Concepts
  • fNIRS fundamentals
    • What fNIRS measures
    • Optodes, sources, detectors, and channels
    • From intensity to concentration: the modified Beer-Lambert law
    • Diffuse optical tomography (DOT)
  • The Cedalion data model
    • NDTimeSeries — the core array type
    • LabeledPoints — probe geometry
    • Recording — the analysis container
    • Quality masks
    • Physical units
  • Typical analysis flow
• Installation
  • Summary
  • Step-by-Step Instructions
    • 1. Install conda
    • 2. Get the source code
    • 3. Select a version
    • 4. Create a conda environment
    • 5. Install Cedalion
    • 6. Optional: Install nirfaster-uFF
  • Using the environment
  • Updating
    • Updating between releases
    • During development
  • Development using Hatch
  • Container Environments
    • Apptainer
      • Building the container:
      • Run jupyter notebook in the container
    • Docker
• Running Notebooks in Google Colab
  • Setup
  • Using your own data
    • 1. Upload data directly to the instance
    • 2. Use Google Drive
• Quick Start
  • 1. Load a recording
  • 2. Inspect the data
  • 3. Convert to optical density
  • 4. Convert to haemoglobin concentration
  • 5. Plot a channel
  • What next?
• Getting started with contributing code to Cedalion
  • Where to get started
  • General rules and overview
    • Style guide for Python code
    • Style guide for docstrings
      • Literature references
    • Where to add code
    • GitHub workflow
  • File and folder structure
  • Example: contributing new functionality
    • Decide where the code belongs
    • Bare-bones function template
    • Worked example: SNR check and channel pruning
    • Creating example notebooks
  • Concluding remarks