ibs-lab · shakiba93 · Jun 24, 2025 · Jun 24, 2025 · Jun 25, 2025 · Jun 27, 2025
diff --git a/LICENSE.md b/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 

diff --git a/README.md b/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.
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -1,5 +1,29 @@
 # Changelog
 
+## Unreleased changes (available on the `dev` branch)
+
+### Added
+- 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))
+### Changed
+- 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).
+
+
+### Deprecated
+### Removed
+### Fixed
+
+- 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)
 
 All dependencies have been updated to recent versions. Please rebuild the environment.

diff --git a/docs/LICENSE.md b/docs/LICENSE.md
diff --git a/docs/_static/css/rtd_fixes.css b/docs/_static/css/rtd_fixes.css
@@ -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;
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -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

diff --git a/docs/data_io/index.rst b/docs/data_io/index.rst
@@ -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
diff --git a/docs/examples/Makefile b/docs/examples/Makefile
@@ -3,16 +3,20 @@ EXAMPLE_NOTEBOOKS = getting_started_io/00_test_installation.ipynb \
                     getting_started_io/11_recording_container.ipynb \
 					getting_started_io/13_data_structures_intro.ipynb \
                     getting_started_io/34_store_hrfs_in_snirf_file.ipynb \
+                    getting_started_io/14_snirf2bids.ipynb \
                     plots_visualization/12_plots_example.ipynb \
                     machine_learning/50_finger_tapping_lda_classification.ipynb \
+                    machine_learning/52_ica_erbm_fingertapping_example.ipynb \
                     modeling/31_glm_basis_functions.ipynb \
                     modeling/32_glm_fingertapping_example.ipynb \
                     modeling/33_glm_illustrative_example.ipynb \
                     modeling/35_statsmodels_overview.ipynb \
+                    modeling/36_glm_workshop.ipynb \
                     signal_quality/20_scalp_coupling_index.ipynb \
                     signal_quality/21_data_quality_and_pruning.ipynb \
                     signal_quality/22_motion_artefacts_and_correction.ipynb \
                     signal_quality/24_downweighting_noisy_channels.ipynb \
+                    signal_quality/25_intro_quality_workshop.ipynb \
                     head_models/40_image_reconstruction.ipynb \
                     head_models/41_photogrammetric_optode_coregistration.ipynb \
                     head_models/42_1010_system.ipynb \

diff --git a/docs/getting_started/colab_setup.md b/docs/getting_started/colab_setup.md
@@ -1,11 +1,13 @@
-## Running Notebooks in Google Colab
+# Running Notebooks in Google Colab
 
-If you would like to test cedalion before going through the installation process on your local machine, you can run the example notebooks through Google Colab. Note that some cedalion features, such as interactive plotting and visualizations, are currently not working in colab. To use these features, you will need to install cedalion on your local machine.
+If you would like to test cedalion before going through the installation process on your local machine, you can run the example notebooks through Google Colab. Note however, that some cedalion features, such as interactive plotting and visualizations, are currently not working in colab. To use these features, you will need to install cedalion on your local machine.
 
-### Setup
+## Setup
 To run a notebook using Google Colab, follow the steps below. Setup should take less than 5 minutes total.
 
-1. Click the link at the top of an example notebook to open it in Google Colab: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)]()
+1. Click the link at the top right of an example notebook to open it in Google Colab: 
+
+   [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)]()
 2. Run the first cell to install the required dependencies.
     - Optional: set options to specify the branch of cedalion to use (--branch).
     ![Colab Cell](../img/colab/colab_cell.png)
@@ -15,12 +17,35 @@ To run a notebook using Google Colab, follow the steps below. Setup should take
 5. Proceed with the rest of the example notebook.
 
 
-### Using your own data
+## Using your own data
+
+You have two options to use your own data in a colab notebook.
+
+### 1. Upload data directly to the instance
 
-Follow these steps to use your own data in a colab notebook.
-    ![File upload](../img/colab/colab_fileupload.jpg)
 1. Click the file icon in the left sidebar.
 2. Click the upload icon (page with arrow).
+   ![File upload](../img/colab/colab_fileupload.jpg) 
 3. Choose the folder/file to upload.
 4. Files can now be accessed in the notebook, for example:
-    ![File access](../img/colab/colab_fileaccess.png)
+   ```python
+   import cedalion.io
+   rec = cedalion.io.read_snirf("uploaded_file.snirf) 
+   ```
+
+5. When the instance is destroyed, uploaded and created files are deleted.
+
+
+
+### 2. Use Google Drive
+During the execution of the first notebook cell, a connection was created between
+your Google Drive and the instance running the notebook. The drive is mounted
+under `/content/drive`.
+
+1. Copy files to you Google Drive.
+2. Files can now be accessed in the notebook, for example:
+   ```python
+   import cedalion.io
+   rec = cedalion.io.read_snirf("/content/drive/path/in/drive/uploaded_file.snirf) 
+   ```
+3. Results saved to Google Drive persist when the instance is destroyed.
diff --git a/docs/getting_started/contributing_code/contributing_code.md b/docs/getting_started/contributing_code/contributing_code.md
@@ -102,10 +102,19 @@ how to dormat these docstrings. We will follow the Google style as described in
 
 Please add references to the literature if you are implementing a published algorithm.
 There is a global bibtex file under `docs/references.bib` to which reference entries
-should be added with a unique bibtex label. Refer to a reference entry with:
+should be added with a unique bibtex label. In docstrings cite a reference entry with:
 ```
     :cite:t:`BIBTEXLABEL`
 ```
+
+In notebooks you can add citations in markdown cells like this:
+```
+    <cite data-cite="Barker2013">(Barker,2013)</cite>
+```
+
+If citations do not show correctly in the rendered documentation, check the Sphinx output for errors while parsing `references.bib`. Duplicate or ill-formed entries are
+often the culprit.
+
 Further options are documented in the 
 [sphinxcontrib-bibtex documentation](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/quickstart.html#minimal-example).