Merge pull request #670 from Remi-Gau/doc

[DOC] improve description of stats output and of bids stats model

Author: Remi-Gau

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -5,11 +5,20 @@ name: Bug report
 
 description: Fill in this template to report a bug
 
-title: "[BUG]: "
+title: "[BUG]"
 
-labels: ["bug"]
+labels: ["bug :bug:"]
 
 body:
+
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+
+        To maximize chances for a quick fix make sure you know
+        [How to Report Bugs Effectively](https://www.chiark.greenend.org.uk/~sgtatham/bugs.html)
+
   - type: checkboxes
     attributes:
       label: Is there an existing issue for this?

README.md

@@ -11,7 +11,7 @@
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
 [![codecov](https://codecov.io/gh/cpp-lln-lab/CPP_SPM/branch/main/graph/badge.svg?token=PMQYH0DIPX)](https://codecov.io/gh/cpp-lln-lab/CPP_SPM)
 [![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)
+[![All Contributors](https://img.shields.io/badge/all_contributors-11-orange.svg?style=flat-square)](https://github.com/cpp-lln-lab/CPP_SPM#contributors)
 
 <!-- markdown-link-check-enable -->
 
@@ -58,7 +58,6 @@ See
 ### Preprocessing
 
 ```matlab
-
 bids_dir = path_to_raw_bids_dataset;
 output_dir = path_to_where_the_output_should_go;
 
@@ -73,7 +72,6 @@ cpp_spm(bids_dir, output_dir, 'subject', ...
 ### GLM
 
 ```matlab
-
 bids_dir = path_to_raw_bids_dataset;
 preproc_dir = path_to_preprocessed_dataset;
 output_dir = path_to_where_the_output_should_go;

docs/source/bids_stats_model.md

@@ -92,9 +92,9 @@ It uses
 to run those transformations. Please see this bids-matlab documentation to know
 how to use them and call them in your JSON.
 
-The advantage of this bids-matlab transformers is
-that they allow you to directly add on tsv files to quickly see
-what outcome a series of transformers will produce.
+The advantage of this bids-matlab transformers is that they allow you to
+directly add on tsv files to quickly see what outcome a series of transformers
+will produce.
 
 Below is an example on how to subtract 3 seconds from the event onsets of the
 conditions `motion` listed in the `trial_type` columns of the `events.tsv` file,
@@ -151,7 +151,7 @@ dummy scans will be included.
             "static"
         ],
         "Model": "spm"
-    }
+}
 ```
 
 `HRF` specifies:
@@ -169,13 +169,43 @@ Not yet implementated:
 
 -   `"fir"`
 
+
+<!--
+```json
+"Model": {
+                            "Type": "glm",
+                            "X": [
+                                "motion", -------- Those 2 conditions will be convolved
+                                "static", -------|   using the canonical HRF only.
+Those 3 conditions      <-------"trans_?",       |
+    will not            <-------"rot_?",         |
+  be convolved.         <-------"*outlier*"      |
+                            ],                   |
+                            "HRF": {             |
+                                "Variables": [   |
+                                    "motion", <--|
+                                    "static"  <--|
+                                ],
+                                "Model": "spm"
+}
+```
+-->
+
+```{image} ./images/gui_batch_model_hrf.png
+:alt: Corresponding options in SPM batch
+:align: center
+```
+
 (bids_stats_model_sofware)=
 
 ### Software
+
 <!-- markdown-link-check-disable -->
+
 Note that if you wanted to change the
 [`SerialCorrelation` model](auto_correlation_model) used by CPP SPM, you could
 do so via the `Software` object of the BIDS stats model.
+
 <!-- markdown-link-check-enable -->
 
 Similar you can adapt directly in the model the threshold used by SPM to create
@@ -207,6 +237,111 @@ of SPM defaults.) .
 }
 ```
 
+```{figure} ./images/gui_batch_model_serialCorrelation_maskThresh.png
+---
+name: software_spm_batch
+align: center
+---
+Corresponding options in SPM batch
+```
+
+### Contrasts
+
+#### Run level
+
+To stay close to the way most SPM users are familiar with, all runs are analyzed
+in one single GLM.
+
+Contrasts are the run level that are either specified using `DummyContrasts` or
+`Contrasts` will be computed and will have the run number appended to their name
+in the SPM gui as shown in {ref}`contrast_run_1` and {ref}`contrast_run_2`.
+
+```{literalinclude} ./examples/model-contrastsRun_smdl.json
+:language: json
+```
+
+```{figure} ./images/gui_contrast_run_1.png
+---
+name: contrast_run_1
+align: center
+---
+Contrast for run 1
+```
+
+```{figure} ./images/gui_contrast_run_2.png
+---
+name: contrast_run_2
+align: center
+---
+Contrast for run 2
+```
+
+#### Subject level
+
+At the moment the only type of model supported at the run level is averaging of
+run level contrasts.
+
+```{literalinclude} ./examples/model-contrastsSubject_smdl.json
+:language: json
+```
+
+```{figure} ./images/gui_contrast_run_1_and_2.png
+---
+name: contrast_subject
+align: center
+---
+Subject level contrast averaging beta of run 1 and 2
+```
+
+## Dataset level
+
+At the moment only, the only type of models that are supported are:
+
+-   one sample t-test: averaging across all subjects
+
+```{literalinclude} ./examples/model-datasetLevel_smdl.json
+   :language: json
+```
+
+-   one sample t-test: averaging across all subjects of a specific group
+
+```{literalinclude} ./examples/model_withinGroup_smdl.json
+   :language: json
+```
+
+-   2 samples t-test: comparing 2 groups
+
+At the moment this can only be based on how participants are allocated to a
+group based on a `group` or `Group` column in the `participants.tsv` of in the
+raw dataset.
+
+```{literalinclude} ./examples/model_betweenGroups_smdl.json
+   :language: json
+```
+
+### Method section
+
+It is possible to write a draft of method section based on a BIDS statistical
+model.
+
+```matlab
+opt.model.file = fullfile(pwd, ...
+                          'models', ...
+                          'model-faceRepetition_smdl.json');
+opt.fwhm.contrast = 0;
+opt = checkOptions(opt);
+
+opt.designType = 'block';
+
+outputFile = boilerplate(opt, ...
+                        'outputPath', pwd, ...
+                        'pipelineType', 'stats');
+```
+
+```{literalinclude} ./examples/stats.md
+   :language: markdown
+```
+
 ## Parametric modulation
 
 Those are not yet fully implemented but there is an example of how to get
@@ -224,8 +359,13 @@ There are several examples of models in the
 [model zoo](https://github.com/bids-standard/model-zoo) along with links to
 their datasets.
 
-Several of the :ref:`demos` have their own model and you can find several
+<!-- markdown-link-check-disable -->
+
+Several of the [demos](demos) have their own model and you can find several
 "dummy" models (without corresponding data) used for testing
+
+<!-- markdown-link-check-enable -->
+
 [in this folder](https://github.com/cpp-lln-lab/CPP_SPM/tree/dev/tests/dummyData/models).
 
 An example of JSON file could look something like that:

docs/source/conf.py

@@ -49,6 +49,8 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["examples", "defaults", "demo", "images/*.md"]
 
+suppress_warnings = ["myst.header"]
+
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
 

docs/source/demos.rst

@@ -1,5 +1,3 @@
-.. _demos:
-
 Demos
 *****
 

docs/source/examples/model-contrastsRun_smdl.json

@@ -0,0 +1,48 @@
+{
+    "Level": "Run",
+    "Name": "run_level",
+    "X": [
+        "olfid_eucalyptus_left",
+        "olfid_eucalyptus_right",
+        "olfid_almond_left",
+        "olfid_almond_right",
+        "olfloc_eucalyptus_left",
+        "olfloc_eucalyptus_right",
+        "olfloc_almond_left",
+        "olfloc_almond_right",
+        "resp_03",
+        "resp_12",
+        1
+    ],
+    "DummyContrasts": {
+        "Contrasts": [
+            "olfid_eucalyptus_left",
+            "olfid_eucalyptus_right",
+            "olfid_almond_left",
+            "olfid_almond_right",
+            "olfloc_eucalyptus_left",
+            "olfloc_eucalyptus_right",
+            "olfloc_almond_left",
+            "olfloc_almond_right"
+        ],
+        "Test": "t"
+    },
+    "Contrasts": [
+        {
+            "Name": "olfid",
+            "ConditionList": [
+                "olfid_eucalyptus_left",
+                "olfid_eucalyptus_right",
+                "olfid_almond_left",
+                "olfid_almond_right"
+            ],
+            "Weights": [
+                1,
+                1,
+                1,
+                1
+            ],
+            "Test": "t"
+        }
+    ]
+}

docs/source/examples/model-contrastsSubject_smdl.json

@@ -0,0 +1,18 @@
+{
+    "Level": "Subject",
+    "Name": "subject_level",
+    "Description": "Only averaging at the subject level is supported for now.",
+    "GroupBy": [
+        "contrast",
+        "subject"
+    ],
+    "Model": {
+        "X": [
+            1
+        ],
+        "Type": "glm"
+    },
+    "DummyContrasts": {
+        "Test": "t"
+    }
+}

docs/source/examples/model-datasetLevel_smdl.json

@@ -0,0 +1,16 @@
+{
+  "Level": "Dataset",
+  "Name": "dataset_level",
+  "GroupBy": [
+    "contrast"
+  ],
+  "Model": {
+    "X": [
+      1
+    ],
+    "Type": "glm"
+  },
+  "DummyContrasts": {
+    "Test": "t"
+  }
+}