Merge branch 'dev' into review/pr-120

Author: emiddell

.github/workflows/run_tests.yml

@@ -7,7 +7,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-13, macos-latest, windows-latest]
+        os: [ubuntu-latest, macos-14, macos-latest, windows-latest]
     runs-on: ${{ matrix.os }}
     defaults:
       run:

.gitignore

@@ -169,6 +169,10 @@ src/cedalion/_version.py
 docs/examples/*.ipynb
 docs/examples/*/*.ipynb
 
+# example plots
+examples/*/*.png
+examples/*/*.gif
+
 # API documentation from sphinx-apidoc
 docs/api/*
 _autosummary*/

LICENSE.md

@@ -1,4 +1,4 @@
-Copyright 2024 The Cedalion Developers
+Copyright 2024-2025 The Cedalion Developers
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this 
 software and associated documentation files (the “Software”), to deal in the Software 

README.md

@@ -1,58 +1,42 @@
+# Cedalion - fNIRS analysis toolbox
+
+A python-based framework for the data-driven analysis of multimodal fNIRS and DOT in naturalistic environments. Developed by the [Intelligent Biomedical Sensing (IBS) Lab](https://ibs-lab.com/) with and for the community.
+
 <p align="center">
-    <img src="docs/img/IBS_clr_small.png" />
+    <img src="docs/img/cedalion_frontpage.png" />
 </p>
 
-# cedalion - fNIRS analysis toolbox
-
-To avoid misinterpretations and to facilitate studies in naturalistic environments, fNIRS measurements will increasingly be combined with recordings from physiological sensors and other neuroimaging modalities.
-The aim of this toolbox is to facilitate this kind of analyses, i.e. it should allow the easy integration of machine learning techniques and provide unsupervised decomposition techniques for
-multimodal fNIRS signals.
 
 ## Documentation
 
 The [documentation](https://doc.ibs.tu-berlin.de/cedalion/doc/dev) contains
-[installation instructions](https://doc.ibs.tu-berlin.de/cedalion/doc/dev/getting_started/installation.html) as
-well as several [example notebooks](https://doc.ibs.tu-berlin.de/cedalion/doc/dev/examples.html)
-that illustrate the functionality of the toolbox.
-For discussions and help you can visit the [cedalion forum on openfnirs.org](https://openfnirs.org/community/cedalion/)
-
-
-## Development environment
-
-To create a conda environment with the necessary dependencies run:
-
-```
-$ conda env create -n cedalion -f environment_dev.yml
-```
-
-Afterwards activate the environment and add an editable install of `cedalion` to it:
-```
-$ conda activate cedalion
-$ pip install -e .
-$ bash install_nirfaster.sh CPU # or GPU
-```
-
-This will also install Jupyter Notebook to run the example notebooks.
-
-If conda is too slow consider using the faster drop-in replacement [mamba](https://mamba.readthedocs.io/en/latest/).
-If you have Miniconda or Anaconda you can install mamba with:
-'''
-$ conda install mamba -c conda-forge
-'''
-and then create the environment with
-```
-$ mamba env create -n cedalion -f environment_dev.yml
-```
-Please note: If this does not socceed there is another route to go:
-Install the libmamba solver
-'''
-$ conda install -n base conda-libmamba-solver
-'''
-and then build the environment with the --solver=libmamba
-```
-$ conda env create -n cedalion -f environment_dev.yml --solver=libmamba
-```
+[installation instructions](https://doc.ibs.tu-berlin.de/cedalion/doc/dev/getting_started/installation.html), an [API reference](https://doc.ibs.tu-berlin.de/cedalion/doc/dev/api/modules.html) as
+well as many [example notebooks](https://doc.ibs.tu-berlin.de/cedalion/doc/dev/examples.html) that illustrate the functionality of the toolbox.
+
+
+
+## Installation
+
+Please refer to the [installation instructions](https://doc.ibs.tu-berlin.de/cedalion/doc/dev/getting_started/installation.html) in the documentation for installing Cedalion
+on you computer.
+
+To test the [example notebooks](https://doc.ibs.tu-berlin.de/cedalion/doc/dev/examples.html) without installing Cedalion locally, you can also [run the notebooks on Google Colab](https://doc.ibs.tu-berlin.de/cedalion/doc/dev/getting_started/colab_setup.html).
+
+## Versions
+The `main` branch acts as a relase branch, i.e. the latest commit there is the most 
+current release. Development happens in the `dev` branch. Please refer to the [CHANGELOG](https://doc.ibs.tu-berlin.de/cedalion/doc/dev/CHANGELOG.html) for a release 
+history and current differences between the `dev` and `main` branches.
+
+
+## Forum
+
+For discussions and help please visit the [Cedalion forum on openfnirs.org](https://openfnirs.org/community/cedalion/)
+
 
 ## How to cite Cedalion
 A paper for the toolbox is currently in the making. If you use this toolbox for a publication in the meantime, please cite us using GitHub's  "Cite this repository" feature in the "About" section. If you want to contact us or learn more about the IBS-Lab please go to https://www.ibs-lab.com/
 
+
+## License
+
+Cedalion is licensed under the MIT license.

docs/CHANGELOG.md

@@ -3,13 +3,43 @@
 ## Unreleased changes (available on the `dev` branch)
 
 ### Added
+- Added the function `cedalion.geometry.landmarks.normalize_landmarks_labels` that case-insensitively maps common landmark labels to canonical names, by [Mohammad Orabe](https://github.com/orabe). ([#132](https://github.com/ibs-lab/cedalion/pull/132))
+- Added functionality and examples for constrained ICA methods (arc-ERBM, arc-EBM),  by [Jacqueline Behrendt](https://github.com/jackybehrendt12). ([#133](https://github.com/ibs-lab/cedalion/pull/133))
 - An example notebook for ICA source extraction was added, by [Jacqueline Behrendt](https://github.com/jackybehrendt12). 
 ([#112](https://github.com/ibs-lab/cedalion/pull/112))
+- Added `TwoSurfaceHeadmodel.scale_to_headsize` and `TwoSurfaceHeadmodel.scale_to_landmarks` to adjust the head model's size to the head circumferences or digitized landmarks, respectively. By [Eike Middell](https://github.com/emiddell).
+- The factory method `cedalion.dot.get_standard_headmodel` to construct the `TwoSurfaceHeadModel` of the standard Colin27 and ICBM-152 heads was added, by [Eike Middell](https://github.com/emiddell).
+- Added `cedalion.xrutils.dot_dataarray_csr` for matrix products between `xr.DataArray` 
+  and `scipy.sparse` arrays, by [Eike Middell](https://github.com/emiddell).
+- Added `cedalion.geometry.landmarks.normalize_landmarks_labels` to map alternative landmark names (e.g., "nasion", "left ear", "nz") to their canonical 10-10 system labels (e.g. Nz, LPA). The function handles now case-insensitive matching and supports common naming conventions. Usage: `geo3d = normalize_landmarks_labels(geo3d)` before calling registration or plotting functions, by [Mohammad Orabe](https://github.com/orabe). ([#84](https://github.com/ibs-lab/cedalion/issues/84))
 ### Changed
+- The package `cedalion.sigproc.motion_correct` was renamed to `cedalion.sigproc.motion`.
+- The ICA-EBM and ICA_ERBM implementations were moved into `cedalion.sigdecomp.unimodal`.
+- The class `cedalion.dot.ForwardModel` accepts also head models that are not in 
+voxel space. They will be transformed to voxel space internally.
+- Refactored `cedalion.plots` into `cedalion.vis` and its subpackages. This cleans up the code structure and should help with discovering existing functions. The package `cedalion.vis.blocks` emphasizes building blocks for larger visualizations. Please refer to `examples/plots_visualization/12_plots_example.ipynb` to get an overview. Importing `cedalion.plots` will throw a deprecation warning to trigger adoption. By [Eike Middell](https://github.com/emiddell).
+- Renamed `LabeledPointCloud` to `LabeledPoints`.
+- Split up the `.nirs` submodule into `.nirs.cw`, `.nirs.fd` and `.nirs.td`. 
+- Merged the submodules `cedalion.datasets` and `cedalion.data`. All functions to
+access example datasets are now available under `cedalion.data`. 
+- The fiducial landmarks of the standard Colin27 and ICBM-152 heads changed. Using the landmark builder 10-10 coordinates were calculated for both heads. These are now 
+  available when head models are created with `get_standard_headmodel`. The example
+  notebook `48_headmodel_landmarks_verification.ipynb` documents the origin of all 
+  landmarksand quantitatively compares the output of the LandmarkBuilder to published
+  coordinates.  By [Eike Middell](https://github.com/emiddell).
+- Added the parameter `mode` to `TwoSurfaceHeadModel.align_and_snap_to_scalp` to switch
+  between constrained affine transformations (translation, rotation, isotropic scaling)
+  and unconstrained affine transformations (also anisotropic scaling, shearing and reflection). The default behaviour from `align_and_snap_to_scalp` was changed from
+  constrained to unconstrained affine transformations. 
+- The image reconstruction methods were refactored to offer more regularization methods     
+  (including spatial basis functions) as well as direct and indirect reconstructions and to provide a simpler interface to the user. All functions are now located under `cedalion.dot`. By [Laura Carlton](https://github.com/lauracarlton), [Alexander von Lühmann](https://github.com/avolu) and [Eike Middell](https://github.com/emiddell). ([#130](https://github.com/ibs-lab/cedalion/pull/86))
+- For the Colin27 and ICBM-152 heads the label for the coordinate reference system was changed from `'aligned'` to `'mni'`.
 - The ninja HD and UHD cap coordinates were changed from a right-handed to a left-handed
 coordinate system, by [Nils Harmening](https://github.com/harmening). ([#110](https://github.com/ibs-lab/cedalion/pull/110))
 - Changed the names of several motion correction algorithms from `motion_correct.motion_correct_X` 
 to `motion_correct.X`. Argument names were made PEP8 compliant. The example `22_motion_artefacts_and_correction` was improved. By [Eike Middell](https://github.com/emiddell).
+- The function `cedalion.vis.anatomy.plot_montage3D` now accepts a `landmarks` parameter to specify which landmarks should be highlighted. Pass `None` (default) to show all available canonical registration landmarks (e.g. Nz, Iz, LPA, RPA, Cz), a list of landmark names to show specific ones, or an empty list to show none, by [Mohammad Orabe](https://github.com/orabe). ([#84](https://github.com/ibs-lab/cedalion/issues/84))
+- Included t-stat thresholding in `cedalion.vis.misc.plot_probe_gui`, by [Shannon Kelley](https://github.com/shankell212). ([#131](https://github.com/ibs-lab/cedalion/pull/131))
 
 
 ### Deprecated
@@ -19,6 +49,10 @@ to `motion_correct.X`. Argument names were made PEP8 compliant. The example `22_
 - Fixed a bug in motion_correct_wavelet affecting the selection of coefficients for IQR-based thresholding. The issue caused unintended suppression of high-frequency components, particularly near the end of recordings. Changed by [Eike Middell](https://github.com/emiddell).
 - Fixed a bug in the stopping criterion of motion_correct.pca_recurse caused by an inverted 
 boolean mask of motion artifacts, by [Eike Middell](https://github.com/emiddell).
+- Fixed an issue with constant regressors when fitting a GLM using the AR-IRLS method. The autoregressive filter used to
+account for serial correlations was not properly applied to them. The fix ignores samples at the beginning of the time
+series until the filter is initialized, by [Eike Middell](https://github.com/emiddell).
+
 
 ## Version 25.1.0 (2025-06-22)
 
@@ -30,7 +64,7 @@ All dependencies have been updated to recent versions. Please rebuild the enviro
 - Spatial and measurement noise regularization options in image reconstruction,  by [David Boas](https://github.com/dboas). ([#86](https://github.com/ibs-lab/cedalion/pull/86))
 - Improved import of optode and electrode coordinates, by [Nils Harmening](https://github.com/harmening). ([#95](https://github.com/ibs-lab/cedalion/pull/95))
 - The interfaces for the fluence and sensitivity computations were changed to allow out-of-core computations, by [Eike Middell](https://github.com/emiddell).
-- Precomputed sensitivities for all example datasets, including the ninjaCap whole head probe, are availabe in cedalion.datasets, by [Eike Middell](https://github.com/emiddell).
+- Precomputed sensitivities for all example datasets, including the ninjaCap whole head probe, are availabe in cedalion.data, by [Eike Middell](https://github.com/emiddell).
 
 - Make all example notebooks run on Google Colab integration, by [Josef Cutler](https://github.com/jccutler). ([#96](https://github.com/ibs-lab/cedalion/pull/96))
 

docs/LICENSE.md

@@ -7,3 +7,7 @@ ul.xr-var-list li.xr-var-item label {
     margin-top: 2px !important;
     margin-bottom: 2px !important;
 }
+
+div.citation .label {
+    width: 5em;
+}

docs/_static/css/rtd_fixes.css

@@ -10,8 +10,8 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "cedalion"
-copyright = "2024, the cedalion developers"
-author = "the cedalion developers"
+copyright = "2024-2025, the Cedalion developers"
+author = "the Cedalion developers"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -84,8 +84,8 @@
 autodoc_type_aliases = {
     "NDTimeSeries" : "cdt.NDTimeSeries",
     "cdt.NDTimeSeries" : "cdt.NDTimeSeries",
-    "LabeledPointCloud" : "cdt.LabeledPointCloud",
-    "cdt.LabeledPointCloud" : "cdt.LabeledPointCloud",
+    "LabeledPoints" : "cdt.LabeledPoints",
+    "cdt.LabeledPoints" : "cdt.LabeledPoints",
     "cedalion.Quantity" : "Quantity",
     "pint.Quantity" : "Quantity",
     "Quantity" : "Quantity",

docs/conf.py

@@ -43,7 +43,7 @@ I/O
    cedalion.io.forward_model
    cedalion.io.photogrammetry
    cedalion.io.probe_geometry
-   cedalion.datasets
+   cedalion.data
 
 
 Examples
@@ -55,4 +55,5 @@ Examples
    ../examples/getting_started_io/10_xarray_datastructs_fnirs.ipynb
    ../examples/getting_started_io/11_recording_container.ipynb
    ../examples/getting_started_io/13_data_structures_intro.ipynb
+   ../examples/getting_started_io/14_snirf2bids.ipynb
    ../examples/getting_started_io/34_store_hrfs_in_snirf_file.ipynb

docs/data_io/index.rst

@@ -0,0 +1,22 @@
+Diffuse optical tomography
+==========================
+
+.. py:currentmodule:: cedalion.dot
+
+
+.. autosummary::
+   :toctree: _autosummary_dot
+   :recursive:
+
+   cedalion.geometry
+
+   cedalion.dot
+
+
+Examples
+--------
+
+.. nbgallery::
+   :glob:
+
+   ../examples/head_models/*