From 6366cae379195bbf32a4486a60f79715f6ff27d3 Mon Sep 17 00:00:00 2001
From: Sebastien Tourbier <sebastien.tourbier1@gmail.com>
Date: Fri, 5 Feb 2021 10:37:48 +0100
Subject: [PATCH] DOC: add description of BIDS entities employed in CMP outputs
 [skip ci]

---
 docs/installation.rst |  2 +-
 docs/outputs.rst      | 26 +++++++++++++++++++++++++-
 2 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/docs/installation.rst b/docs/installation.rst
index 53aad030c..7e66f1ff5 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -139,7 +139,7 @@ The installation of the Connectome Mapper 3 BIDS App Manager (CMPBIDSAPPManager)
   It seems there is no conda package for `git-annex` available on Mac. For your convenience, we created an additional `environment_macosx.yml` miniconda3 environment where the line `- git-annex=7.20190219` has been removed.
   Git-annex should be installed on MacOSX using brew (https://brew.sh/index_fr) i.e. ``brew install git-annex``. See https://git-annex.branchable.com/install/ for more details.
 
-  Note that `git-annex` is only necessary if you wish to use BIDS datasets managed by Datalad (https://www.datalad.org/), a very experimental feature. For the moment, I would not recommend to use right now as it is still in a beta-testing phase.
+  Note that `git-annex` is only necessary if you wish to use BIDS datasets managed by Datalad (https://www.datalad.org/), a very experimental feature still in beta-testing phase.
 
 * Activate the conda environment::
 
diff --git a/docs/outputs.rst b/docs/outputs.rst
index 379babbad..60c4906c4 100644
--- a/docs/outputs.rst
+++ b/docs/outputs.rst
@@ -4,6 +4,30 @@ Outputs of Connectome Mapper 3
 
 Processed, or derivative, data are outputed to ``<bids_dataset/derivatives>/``.
 
+BIDS derivatives entities
+--------------------------
+
+.. tabularcolumns:: |l|p{5cm}|
+
++--------------------------+------------------------------------------------------------------------------------------------------------+
+| **Entity**               | **Description**                                                                                            |
++==========================+============================================================================================================+
+| ``sub-<label>``          | Distinguish different subjects                                                                             |
++--------------------------+------------------------------------------------------------------------------------------------------------+
+| ``ses-<label>``          | Distinguish different acquisition sessions                                                                 |
++--------------------------+------------------------------------------------------------------------------------------------------------+
+| ``label-<label>``        | Describe the type of brain tissue segmented (for _probseg/dseg) or the parcellation atlas (for _atlas)     |
++--------------------------+------------------------------------------------------------------------------------------------------------+
+| ``space-DWI``            | Distinguish anatomical MRI derivatives in the target diffusion MRI space                                   |
++--------------------------+------------------------------------------------------------------------------------------------------------+
+| ``model-<label>``        | Distinguish different diffusion signal models (DTI, CSD, SHORE, MAPMRI)                                    |
++--------------------------+------------------------------------------------------------------------------------------------------------+
+
+See `Original BIDS Entities Appendix <https://bids-specification.readthedocs.io/en/v1.4.1/99-appendices/09-entities.html>`_ for more description.
+
+.. note:: A new suffix `_atlas` has been introduced, that is used in combination with the ``label-<atlas_label>`` entity (where ``<atlas_label>``:``Desikan``/``L2008``/``L2018``) to distinguish different parcellation atlas outputs.
+
+
 Main Connectome Mapper Derivatives
 ==========================================
 
@@ -133,7 +157,7 @@ Diffusion derivatives in the individual ``DWI`` space are placed in each subject
     where:
 
     - ``<model_label>`` is the diffusion model used to drive tractography (DTI, CSD, SHORE)
-    - ``<model_label>`` is the type of tractography algorithm employed (DET for deterministic, PROB for probabilistic)
+    - ``<label>`` is the type of tractography algorithm employed (DET for deterministic, PROB for probabilistic)
 
 * The structural connectivity (SC) graphs: