cpp-lln-lab · Remi-Gau · May 17, 2022 · May 16, 2022 · May 17, 2022 · May 17, 2022
diff --git a/.github/workflows/check_md_links.yml b/.github/workflows/check_md_links.yml
@@ -16,3 +16,6 @@ jobs:
     steps:
     - uses: actions/checkout@master
     - uses: gaurav-nelson/github-action-markdown-link-check@v1
+      with:
+        use-quiet-mode: 'yes'
+        use-verbose-mode: 'yes'
diff --git a/.gitmodules b/.gitmodules
@@ -27,3 +27,7 @@
 [submodule "lib/MACS"]
 	path = lib/MACS
 	url = https://github.com/cpp-lln-lab/MACS.git
+[submodule "lib/octache"]
+	path = lib/octache
+	url = https://github.com/Remi-Gau/Octache.git
+	datalad-url = https://github.com/Remi-Gau/Octache.git
diff --git a/Makefile b/Makefile
@@ -31,7 +31,7 @@ test: run_tests.m initCppSpm.m src tests
 docker_images: Dockerfile Dockerfile_dev
 	bash build_image.sh
 
-
+# TODO should update the version in the doc and in the reference in the README
 version.txt: CITATION.cff
 	grep -w "^version" CITATION.cff | sed "s/version: /v/g" > version.txt
 
@@ -40,3 +40,5 @@ validate_cff: CITATION.cff
 
 manual:
 	cd docs && sh create_manual.sh
+
+# TODO update contributors in code and citation CFF based on contributors?
diff --git a/README.md b/README.md
@@ -1,3 +1,5 @@
+<!-- markdown-link-check-disable -->
+
 [![Documentation Status: stable](https://readthedocs.org/projects/cpp_spm/badge/?version=stable)](https://cpp_spm.readthedocs.io/en/stable/?badge=stable)
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/cpp-lln-lab/CPP_SPM/dev)
 [![miss_hit_quality](https://github.com/cpp-lln-lab/CPP_SPM/actions/workflows/miss_hit_quality.yml/badge.svg)](https://github.com/cpp-lln-lab/CPP_SPM/actions/workflows/miss_hit_quality.yml)
@@ -10,22 +12,65 @@
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3554331.svg)](https://doi.org/10.5281/zenodo.3554331)
 [![All Contributors](https://img.shields.io/badge/all_contributors-10-orange.svg?style=flat-square)](https://github.com/cpp-lln-lab/CPP_SPM#contributors)
 
+<!-- markdown-link-check-enable -->
+
 # CPP SPM
 
 This is a Matlab / Octave toolbox to perform MRI data analysis on a
 [BIDS data set](https://bids.neuroimaging.io/) using SPM12.
 
-## Installation
+## Installation and set up
 
 ```bash
 git clone \
     --recurse-submodules \
     https://github.com/cpp-lln-lab/CPP_SPM.git
 ```
 
+To get the latest version that is on the `dev` branch.
+
+```bash
+git clone \
+    --recurse-submodules \
+    --branch dev \
+    https://github.com/cpp-lln-lab/CPP_SPM.git
+```
+
+To start using CPP_SPM, you just need to initialize it for this MATLAB / Octave
+session with::
+
+```matlab
+cpp_spm()
+```
+
 Please see our
-[documentation](https://cpp_spm.readthedocs.io/en/latest/index.html) for more
-info.
+[documentation](https://cpp-spm.readthedocs.io/en/dev/general_information.html)
+for more info.
+
+## Usage
+
+For some of its functionality cpp_spm has a BIDS app like API:
+
+### Preprocessing
+
+```matlab
+cpp_spm(bids_dir, output_dir, 'participant', ...
+        'action', 'preprocess', ...
+        'task', {...})
+```
+
+### GLM
+
+```matlab
+cpp_spm(bids_dir, output_dir, 'participant', ...
+        'action', 'preprocess', ...
+        'preproc_dir', preproc_dir, ...
+        'model_file', model_file)
+```
+
+Please see our
+[documentation](https://cpp-spm.readthedocs.io/en/dev/bids_app_api.html) for
+more info.
 
 ## Features
 
@@ -35,8 +80,8 @@ If your data is fairly "typical" (for example whole brain coverage functional
 data with one associated anatomical scan for each subject), you might be better
 off running [fmriprep](https://fmriprep.org/en/stable/) on your data.
 
-If you have more exotic data that cannot be handled well by fmriprep then CPP_SPM
-has some automated workflows to perform amongst other things:
+If you have more exotic data that cannot be handled well by fmriprep then
+CPP_SPM has some automated workflows to perform amongst other things:
 
 -   slice timing correction
 
@@ -56,9 +101,9 @@ filenames.
 
 ### Statistics
 
-The model specification are done via the
-[BIDS stats model](https://docs.google.com/document/d/1bq5eNDHTb6Nkx3WUiOBgKvLNnaa5OMcGtD0AZ9yms2M/edit?usp=sharing)
-and can be used to perform:
+The model specification are set up using the
+[BIDS stats model](https://bids-standard.github.io/stats-models/intro.html) and
+can be used to perform:
 
 -   whole GLM at the subject level
 -   whole brain GLM at the group level à la SPM (meaning using a summary
@@ -78,13 +123,14 @@ info.
 ## Citation
 
 ```bibtex
-    @software{CPP_SPM,
-        author = {Gau, Rémi and Barilari, Marco and Battal, Ceren and Rezk, Mohamed and Collignon, Olivier and Gurtubay, Ane and Falagiarda, Federica and MacLean, Michèle and Cerpelloni, Filippo},
-        license = {GPL-3.0},
-        title = {{CPP SPM}},
-        url = {https://github.com/cpp-lln-lab/CPP_SPM},
-        version = {1.1.3dev}
-    }
+@software{CPP_SPM,
+  author  = {Gau, Rémi and Barilari, Marco and Battal, Ceren and Rezk, Mohamed and Collignon, Olivier and Gurtubay, Ane and Falagiarda, Federica and MacLean, Michèle and Cerpelloni, Filippo},
+  license = {GPL-3.0},
+  title   = {CPP SPM},
+  url     = {https://github.com/cpp-lln-lab/CPP_SPM},
+  version = {1.1.5dev},
+  doi     = {https://doi.org/10.5281/zenodo.3554331},
+}
 ```
 
 ## Contributors

diff --git a/cpp_spm.m b/cpp_spm.m
@@ -317,6 +317,7 @@ function initCppSpm(dev)
     printCredits(opt);
 
     run(fullfile(thisDirectory, 'lib', 'CPP_ROI', 'initCppRoi'));
+    run(fullfile(thisDirectory, 'lib', 'octache', 'setup'));
 
     %%
     if isOctave

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -46,7 +46,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = ["examples"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"

diff --git a/docs/source/examples/preprocess.md b/docs/source/examples/preprocess.md
@@ -0,0 +1,51 @@
+The fMRI data were pre-processed with CPP SPM (v1.1.5dev;
+https://github.com/cpp-lln-lab/CPP_SPM; DOI:
+https://doi.org/10.5281/zenodo.3554331) using statistical parametric mapping
+(SPM12 - 7771; Wellcome Center for Neuroimaging, London, UK;
+https://www.fil.ion.ucl.ac.uk/spm; RRID:SCR_007037) using MATLAB 9.2.0.538062 (R2017a)
+on a unix computer (Ubuntu 18.04.6 LTS).
+
+The preprocessing of the functional images was performed in the following order:
+
+-   removing of dummy scans
+-   slice timing correction
+-   realignment and unwarping
+-   segmentation and skullstripping
+-   normalization MNI space
+-   smoothing
+
+4 dummy scans were removed to allow signal stabilization.
+
+Slice timing correction was performed taking the 16^th slice as a reference
+(interpolation: sinc interpolation).
+
+Functional scans from each participant were realigned and unwarped using the
+mean image as a reference (SPM single pass; number of degrees of freedom: 6 ;
+cost function: least square) (Friston et al, 1995).
+
+The anatomical image was bias field corrected. The bias field corrected image
+was segmented and normalized to MNI space (target space: IXI549Space; target
+resolution: 1 mm; interpolation: 4th degree b-spline) using a unified
+segmentation.
+
+The tissue propability maps generated by the segmentation were used to
+skullstripp the bias corrected image removing any voxel with p(gray matter) +
+p(white matter) + p(CSF) > 0.75.
+
+The mean functional image obtained from realignement was co-registered to the
+bias corrected anatomical image (number of degrees of freedom: 6 ; cost
+function: normalized mutual information) (Friston et al, 1995). The
+transformation matrix from this coregistration was applied to all the functional
+images.
+
+The deformation field obtained from the segmentation was applied to all the
+functional images (target space: IXI549Space; target resolution: equal to that
+used at acquisition; interpolation: 4th degree b-spline).
+
+Preprocessed functional images were spatially smoothed using a 3D gaussian
+kernel (FWHM = 6 mm).
+
+This method section was automatically generated using CPP SPM (v1.1.5dev;
+https://github.com/cpp-lln-lab/CPP_SPM; DOI:
+https://doi.org/10.5281/zenodo.3554331) and octache
+(https://github.com/Remi-Gau/Octache).
diff --git a/docs/source/examples/stats.md b/docs/source/examples/stats.md
@@ -0,0 +1,31 @@
+The fMRI data were analysed with CPP SPM (v1.1.5dev;
+https://github.com/cpp-lln-lab/CPP_SPM; DOI:
+https://doi.org/10.5281/zenodo.3554331) using statistical parametric mapping
+(SPM12 - 7771; Wellcome Center for Neuroimaging, London, UK;
+https://www.fil.ion.ucl.ac.uk/spm; RRID:SCR_007037) using MATLAB 9.2.0.538062 (R2017a)
+on a unix computer (Ubuntu 18.04.6 LTS).
+
+The input data were the preprocessed BOLD images in individual IXI549Space space
+for the task "facerepetition".
+
+At the subject level, we performed a mass univariate analysis with a linear
+regression at each voxel of the brain, using generalized least squares with a
+global AR(1) model to account for temporal auto-correlation and a drift fit with
+discrete cosine transform basis (128.2051 seconds cut-off).
+
+Image intensity scaling was done run-wide before statistical modeling such that
+the mean image would have a mean intracerebral intensity of 100.
+
+We modeled the fMRI experiment in a block design with regressors entered into
+the run-specific design matrix. The the onsets
+were convolved with a canonical hemodynamic response function (HRF) and its
+temporal and dispersion derivatives for the conditions: famous_1, famous_2,
+unfamiliar_1, unfamiliar_2.
+
+Nuisance covariates included the 6 realignment parameters to account for
+residual motion artefacts.
+
+This method section was automatically generated using CPP SPM (v1.1.5dev;
+https://github.com/cpp-lln-lab/CPP_SPM; DOI:
+https://doi.org/10.5281/zenodo.3554331) and octache
+(https://github.com/Remi-Gau/Octache).
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -23,7 +23,7 @@ Welcome to CPP SPM documentation!
    statistics
    quality_analysis
    FAQ
-   method_section_boilerplate
+   method_section
    mancoreg
    docker
    links_and_references

diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -50,7 +50,7 @@ with the following git command::
 If you need the latest development, then you must clone from the ``dev`` branch::
 
   git clone \
-      -b dev \
+      --branch dev \
       --recurse-submodules \
       https://github.com/cpp-lln-lab/CPP_SPM.git
 

diff --git a/docs/source/method_section.rst b/docs/source/method_section.rst
@@ -0,0 +1,42 @@
+Methods section
+***************
+
+.. automodule:: src.reports
+
+Dataset description
+===================
+
+Use the ``reportBIDS`` function to description of your dataset
+that can be used for your methods section
+
+.. autofunction:: reportBIDS
+
+Preprocessing & GLM
+===================
+
+This can be generated with the ``boilerplate`` function.
+
+.. autofunction:: boilerplate
+
+Output example - Preprocessing
+------------------------------
+
+.. literalinclude:: examples/preprocess.md
+   :language: text
+
+Output example - GLM subject level
+----------------------------------
+
+.. literalinclude:: examples/stats.md
+   :language: text
+
+Output example - GLM Group level
+--------------------------------
+
+WIP
+
+References
+==========
+
+.. literalinclude:: references.bib
+   :language: bibtex