Changelog

Version 26.5.0 (2026-05-27)

Additions and Changes

Structure and Renaming:

  • 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.

  • 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.

  • 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.

  • 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.

Head Models & Registration

  • 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.

  • Added TwoSurfaceHeadmodel.align_and_relax_to_scalp to conform montages to the scalp surface using a spring-relaxation method that minimizes channel distance distortions. By Eike Middell.

  • Added higher-resolution cortex meshes for the Colin27 and ICBM152 head models, which additionally maintain a link to the Freesurfer surfaces from which they were derived. The Colin27 and ICBM-152 meshes were subsequently recomputed to remove artifacts. Reduced meshes of the FreeSurfer inflated brains are now bundled with a 1-to-1 vertex correspondence to the pial brain meshes. A mechanism for deriving parcel-aware, sparse voxel-to-vertex maps, that are stored in Matrix Market format, was added. By Eike Middell. (#138).

  • Added TwoSurfaceHeadmodel.assign_parcels_via_mni_coords for applying other parcellation schemes to brain vertices using a volumetric atlas in MNI space, by Eike Middell.

  • 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.

  • 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 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.

  • For the Colin27 and ICBM-152 heads the label for the coordinate reference system was changed from 'aligned' to 'mni'.

  • 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. (#84, #132)

  • The ninja HD and UHD cap coordinates were changed from a left-handed to a right-handed coordinate system, by Nils Harmening. (#110)

Image Reconstruction

  • 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, Alexander von Lühmann and Eike Middell. (#130)

  • Added cedalion.dot.ImageRecon.get_image_noise_posterior, by Laura Carlton. (#134)

  • The class cedalion.dot.ForwardModel accepts also head models that are not in voxel space. They will be transformed to voxel space internally.

  • The normalization of the dot.GaussianSpatialBasisFunctions was changed to match the original implementation used in [CAK+26].

GLM

  • Generalized the GLM fit routine and regressors to work not only in channel space but also on time series with other spatial dimensions (vertices, parcels,…). Center higher-order drift regressors in design_matrix.drift_regressors. By Miray Altinkaynak and Reihaneh Taghizadegan. (#120, #142)

  • Previously, HRF regressors in the GLM where constructed from normalized basis functions and were normalized again after they were convolved over the stimulus duration. Now, only the basis functions are normalized to 1. (#139).

Signal Processing

Visualization

  • 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. (#84)

  • Included t-stat thresholding in cedalion.vis.misc.plot_probe_gui, by Shannon Kelley. (#131)

  • Added the option draw_arcs to cedalion.vis.anatomy.scalp_plot. If set to True, channels are drawn as curved lines to reduce overlap, by Eike Middell.

  • Added channel plotting (lines between source-detector pairs) to cedalion.vis.blocks.plot_labeled_points, by Nils Harmening. (#111)

  • Enhanced landmark picking in cedalion.vis.blocks.plot_surface: callers can now choose which landmarks to pick, and the picked landmarks are returned as an xr.DataArray, by Nils Harmening. (#126)

Utilities

  • Added cedalion.xrutils.dot_dataarray_csr for matrix products between xr.DataArray and scipy.sparse arrays, by Eike Middell.

  • Added a Dockerfile to build a containerised cedalion environment, by Nils Harmening. (#6)

  • Added cedalion.bibliography.Bibliography, a container for collecting references. An instance of this class is instantiated as cedalion.bib which is used by functions throughout the toolbox for citing used methods. At the end of a notebook, a call to cedalion.bib.dump_to_notebook() produces a list of references. By Eike Middell. (#153)

  • Added cedalion.io.bids.load_from_bids_optodes_tsv and cedalion.io.bids.export_to_bids_optodes_tsv for handling BIDS-compliant optode geometry files. By Eike Middell.

Fixes

  • 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.

  • Fixed a bug in the stopping criterion of motion_correct.pca_recurse caused by an inverted boolean mask of motion artifacts, by Eike Middell.

  • 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.

  • Fixed the labels assigned by landmark picking in cedalion.vis.blocks.plot_surface, by Nils Harmening. (#126)

  • Fixed cedalion.io.read_photogrammetry_einstar to filter out unpicked positions, by Nils Harmening. (#144)

  • Removed a redundant t_ras2ijk transform when saving and loading TwoSurfaceHeadModels, by Nils Harmening. (#143)

  • Fixed TwoSurfaceHeadModel.__repr__ raising when landmarks was None, by Eike Middell.

  • Fixed a bug caused by mutable inputs in snap_to_scalp_voxels, by Nils Harmening. (#160)

  • Fixed a bug caused by mutable inputs in TwoSurfaceHeadModel, by Nils Harmening. (#163)

  • Fixed a bug in TwoSurfaceHeadModel.scale_to_landmarks caused by Xarray contracting over all common dimensions in cases where CRS names did not differ, by Nils Harmening. (#165)

  • Fixed a bug in TwoSurfaceHeadModel.scale_to_landmarks caused by Xarray contracting over all common dimensions in cases where CRS names did not differ, by Nils Harmening. (#165)

  • Fixed a bug in TwoSurfaceHeadModel.load and .save caused by asymmetric assumptions in both functions , by Nils Harmening. (#164)

Version 25.1.0 (2025-06-22)

All dependencies have been updated to recent versions. Please rebuild the environment.

New Features:

  • Added Schaefer atlas-based parcel labels for ICBM152 and Colin27 head models via FreeSurfer surface mapping, by Shakiba Moradi.

  • Spatial and measurement noise regularization options in image reconstruction, by David Boas. (#86)

  • Improved import of optode and electrode coordinates, by Nils Harmening. (#95)

  • The interfaces for the fluence and sensitivity computations were changed to allow out-of-core computations, by Eike Middell.

  • Precomputed sensitivities for all example datasets, including the ninjaCap whole head probe, are availabe in cedalion.data, by Eike Middell.

  • Make all example notebooks run on Google Colab integration, by Josef Cutler. (#96)

  • Added functionality to add synthetic HRFs to resting state data, by Thomas Fischer. (#77)

  • Added functionality to add synthetic artifacts to fNIRS data , by Josef Cutler.

  • Added AMPD algorithm for heart beat detection from [SBW12], by Isa Musisi.

  • Functionality for global physiology removal, by Alexander von Lühmann. (#106)

  • Multimodal source decomposition methods, including most CCA variants, by Tomas Codina. (#102)

  • The interface to fit GLMs changed. The GLM solver is now based on statsmodels and we integrated the AR-IRLS algorithm, by Ted Huppert and Eike Middell. (#68)

  • Added wavelet motion correction from [MD12], by Josef Cutler. (#72)

  • New multi-view animated image reconstruction plots, by David Boas and Alexander von Lühmann.

  • Thresholding and visualizing probe sensitivity to brain parcels, by Alexander von Lühmann.

  • Improvements to the time-series plots, by David Boas. (#85, #108)

Bugfixes:

Version 25.0.0 (2025-01-21)