merge dev into parcel-voxel-information

Author: harmening

.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*/

docs/CHANGELOG.md

@@ -5,7 +5,28 @@
 ### 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))
+- 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).
 ### Changed
+- 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` 
@@ -34,7 +55,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/conf.py

@@ -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/data_io/index.rst

@@ -43,7 +43,7 @@ I/O
    cedalion.io.forward_model
    cedalion.io.photogrammetry
    cedalion.io.probe_geometry
-   cedalion.datasets
+   cedalion.data
 
 
 Examples

docs/dot/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/*

docs/examples/Makefile

@@ -24,6 +24,7 @@ EXAMPLE_NOTEBOOKS = getting_started_io/00_test_installation.ipynb \
                     head_models/44_head_models.ipynb \
                     head_models/45_parcel_sensitivity.ipynb \
                     head_models/46_precompute_fluence.ipynb \
+                    head_models/48_headmodel_landmarks_verification.ipynb \
                     augmentation/61_synthetic_artifacts_example.ipynb \
                     augmentation/62_synthetic_hrfs_example.ipynb \
                     physio/71_ampd_heartbeat.ipynb

docs/getting_started/contributing_code/contributing_code.md

@@ -17,15 +17,15 @@ It is smart to make yourself aware of five resources and concepts that build the
 # get example finger tapping dataset
 import cedalion
 import cedalion.nirs
-import cedalion.datasets as datasets
+import cedalion.data
 import xarray as xr
 
-snirf_element = datasets.get_fingertapping()
+snirf_element = cedalion.data.get_fingertapping()
 amp = snirf_element[0].data[0]
 geo = snirf_element[0].geo3d
-od = cedalion.nirs.int2od(amp)
+od = cedalion.nirs.cw.int2od(amp)
 dpf = xr.DataArray([6, 6], dims="wavelength", coords={"wavelength" : amp.wavelength})
-conc = cedalion.nirs.beer_lambert(amp, geo, dpf)
+conc = cedalion.nirs.cw.beer_lambert(amp, geo, dpf)
 meas_list = snirf_element[0].measurement_lists[0]
 
 data = xr.Dataset(
@@ -153,7 +153,7 @@ Widely used general functionality is part of the files on the top level (e.g. ni
 | **data** | Look up tables and other small datasets often required for ecexuting functions. |
 | **dataclasses** | Dataclass definitions that are used in Cedalion. Example: in xrschemas.py you can find that we work with xarray objects (see more detail in the next section). For time series data these have to have at least two dimensions: "time" and "channel".  |
 | **geometry** | Functions for geometric manipulations, e.g. for optode registration, building landmarks on a 3D head, head segmentation, etc. |
-| **imagereco** | Functions for DOT image reconstruction |
+| **dot** | Functions for DOT image reconstruction |
 | **io** | Functions for reading and writing data to and from Cedalion. This includes for instance fnirs data in snirf format, probe geometries or reading anatomies (e.g. segmentation masks). |
 | **models** | Functions for data modelling, for instance the General Linear Model (GLM).|
 | **sigdecomp** | Functions for signal decomposition methods that are not part of a standard python distribution, e.g. advanced ICA methods.|

docs/image_reco/index.rst

@@ -1,10 +1,13 @@
 # Cedalion
 
-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 with and for the community.
+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 
+with and for the community.
 
 ![cedalion graphical abstract](img/cedalion_frontpage.png)
 
-You can find the [github repository for the cedalion toolbox here](https://github.com/ibs-lab/cedalion).
+You can find the 
+[github repository for the cedalion toolbox here](https://github.com/ibs-lab/cedalion).
 
 ```{toctree}
 :maxdepth: 1
@@ -25,7 +28,7 @@ community/index.md
 data_io/index
 sigproc/index
 machine_learning/index
-image_reco/index
+dot/index
 physio/index
 plot_vis/index
 synth/index