[DOC] Add documentation for reconstruction method option (#1300)

* document reconstruction method option and clarify file reader error

* Apply suggestions from code review

Co-authored-by: AliceJoubert <[email protected]>

* fix broken adni link

* add link to adni pet documentation

---------

Co-authored-by: AliceJoubert <[email protected]>

Author: NicolasGensollen

clinica/utils/pet.py

@@ -39,7 +39,7 @@ class ReconstructionMethod(str, Enum):
 
     For ADNI specific reconstruction methods, see:
 
-    https://adni.loni.usc.edu/methods/pet-analysis-method/pet-analysis/
+    https://adni.loni.usc.edu/data-samples/adni-data/neuroimaging/pet/
     """
 
     # Reconstruction methods defined in the BIDS specifications

docs/Pipelines/PET_Introduction.md

@@ -35,6 +35,27 @@ bids
       └─ sub-CLNC001_ses-M000_trc-18FFDG_pet.nii.gz
 ```
 
+## Reconstruction methods
+
+PET data can be reconstructed into the spatial distribution of the injected radio-tracer through various methods.
+The specification of the method used to reconstruct a given image is supported by the [BIDS standard](https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/09-positron-emission-tomography.html#pet-recording-data).
+
+There exists four reserved values:
+
+- `acdyn`: for reconstructions with attenuation correction of dynamic data
+- `acstat`: for reconstructions with attenuation correction of static data
+- `nacdyn`: for reconstructions without attenuation correction of dynamic data
+- `nacstat`: for reconstructions without attenuation correction of static data
+
+In addition to these values, when working with ADNI data, the following values are possible:
+
+- `coregdyn`: Corresponds to "ADNI processing steps 1"
+- `coregavg`: Corresponds to "ADNI processing steps 2"
+- `coregstd`: Corresponds to "ADNI processing steps 3"
+- `coregiso`: Corresponds to "ADNI processing steps 4"
+
+See [this page](https://adni.loni.usc.edu/data-samples/adni-data/neuroimaging/pet/) for more information.
+
 ## Reference regions used for intensity normalization
 
 In neurology, an approach widely used to allow inter- and intra-subject comparison of [PET](../glossary.md#pet) images is to compute standardized uptake value ratio ([SUVR](../glossary.md#suvr)) maps.

docs/Pipelines/PET_Linear.md

@@ -4,23 +4,17 @@
 This pipeline performs spatial normalization to the MNI space and intensity normalization of [PET](../glossary.md#pet) images.
 Its steps include:
 
-- affine registration to the [MNI152NLin2009cSym](https://bids-specification.readthedocs.io/en/stable/99-appendices/08-coordinate-systems.html#template-based-coordinate-systems)
-template [Fonov et al., [2011](https://doi.org/10.1016/j.neuroimage.2010.07.033),
-[2009](https://doi.org/10.1016/S1053-8119(09)70884-5)] in MNI space with the
-SyN algorithm [[Avants et al., 2008](https://doi.org/10.1016/j.media.2007.06.004)]
-from the [ANTs](http://stnava.github.io/ANTs/) software package
-[[Avants et al., 2014](https://doi.org/10.3389/fninf.2014.00044)];
-- intensity normalization using the average [PET](../glossary.md#pet) uptake in reference regions
-resulting in a standardized uptake value ratio ([SUVR](../glossary.md#suvr)) map;
-- cropping of the registered images to remove the background.
+- affine registration to the [MNI152NLin2009cSym](https://bids-specification.readthedocs.io/en/stable/99-appendices/08-coordinate-systems.html#template-based-coordinate-systems) template [Fonov et al., [2011](https://doi.org/10.1016/j.neuroimage.2010.07.033), [2009](https://doi.org/10.1016/S1053-8119(09)70884-5)] in MNI space with the SyN algorithm [[Avants et al., 2008](https://doi.org/10.1016/j.media.2007.06.004)] from the [ANTs](http://stnava.github.io/ANTs/) software package [[Avants et al., 2014](https://doi.org/10.3389/fninf.2014.00044)]
+- intensity normalization using the average [PET](../glossary.md#pet) uptake in reference regions resulting in a standardized uptake value ratio ([SUVR](../glossary.md#suvr)) map
+- cropping of the registered images to remove the background
 
 !!! note "Clinica & BIDS specifications for PET modality"
     Since Clinica `v0.6`, PET data following the official specifications in BIDS version 1.6.0 are now compatible with Clinica.
     See [BIDS](../../BIDS) page for more information.
 
 ## Prerequisites
 
-You need to have performed the [`t1-linear`](../T1_Linear) pipeline on your T1-weighted MR images.
+You need to have performed the [`t1-linear`](./T1_Linear.md) pipeline on your T1-weighted MR images.
 
 ## Dependencies
 
@@ -37,36 +31,35 @@ clinica run pet-linear [OPTIONS] BIDS_DIRECTORY CAPS_DIRECTORY ACQ_LABEL
 
 where:
 
-- `BIDS_DIRECTORY` is the input folder containing the dataset in a
-[BIDS](../../BIDS) hierarchy;
-- `CAPS_DIRECTORY` is the output folder containing the results in a
-[CAPS](../../CAPS/Introduction) hierarchy;
-- `ACQ_LABEL` is the label given to the PET acquisition, specifying the tracer
-used (`trc-<acq_label>`). It can be for instance '18FFDG' for
-<sup>18</sup>F-fluorodeoxyglucose or '18FAV45' for <sup>18</sup>F-florbetapir;
-- The reference region is used to perform intensity normalization (i.e.
-  dividing each voxel of the image by the average uptake in this region)
-  resulting in a standardized uptake value ratio ([SUVR](../glossary.md#suvr)) map. It can be
-  `cerebellumPons` or `cerebellumPons2` (used for amyloid tracers) and `pons`
-  or `pons2` (used for FDG). See [PET introduction](./PET_Introduction.md) for
-  more details about masks versions.
-
-By default, cropped images (matrix size 169×208×179, 1 mm isotropic voxels) are
-generated to reduce the computing power required when training deep learning
-models. Use the `--uncropped_image` option if you do not want to crop the image.
-
-The pipeline also offers the possibility to save the [PET](../glossary.md#pet) image in the T1w space
-after rigid transformation using the `--save_pet_in_t1w_space` option.
+- `BIDS_DIRECTORY` is the input folder containing the dataset in a [BIDS](../BIDS.md) hierarchy
+- `CAPS_DIRECTORY` is the output folder containing the results in a [CAPS](../CAPS/Introduction.md) hierarchy
+- `ACQ_LABEL` is the label given to the PET acquisition, specifying the tracer used (`trc-<acq_label>`). It can be for instance '18FFDG' for <sup>18</sup>F-fluorodeoxyglucose or '18FAV45' for <sup>18</sup>F-florbetapir
+- The reference region is used to perform intensity normalization (i.e. dividing each voxel of the image by the average uptake in this region) resulting in a standardized uptake value ratio ([SUVR](../glossary.md#suvr)) map.
+  It can be `cerebellumPons` or `cerebellumPons2` (used for amyloid tracers) and `pons` or `pons2` (used for FDG).
+  See [PET introduction](./PET_Introduction.md) for more details about masks versions.
+
+By default, cropped images (matrix size 169×208×179, 1 mm isotropic voxels) are generated to reduce the computing power required when training deep learning models.
+Use the `--uncropped_image` option if you do not want to crop the image.
+
+It is possible to select only images based on a [specific reconstruction method](./PET_Introduction.md#reconstruction-methods) with the `--reconstruction_method` option.
+
+!!! warning
+    It can happen that a [BIDS](../BIDS.md) dataset contains several [PET](../glossary.md#pet) scans for a given subject and session.
+    In this situation, these images will differ through at least one [BIDS](../BIDS.md) entity like the tracer or the reconstruction method.
+    When running the `pet-linear` pipeline, clinica will raise an error if more than one image matches the criteria provided through the command line.
+    To avoid that, it is important to specify values for these options such that a single image is selected per subject and session.
+
+The pipeline also offers the possibility to save the [PET](../glossary.md#pet) image in the T1w space after rigid transformation using the `--save_pet_in_t1w_space` option.
 
 !!! note
-    The arguments common to all Clinica pipelines are described in [Interacting with Clinica](../../InteractingWithClinica).
+    The arguments common to all Clinica pipelines are described in [Interacting with Clinica](../Software/InteractingWithClinica.md).
 
 !!! tip
     Do not hesitate to type `clinica run pet-linear --help` to see the full list of parameters.
 
 ## Outputs
 
-Results are stored in the following folder of the [CAPS hierarchy](../../CAPS/Specifications/#pet-imaging-data): `subjects/<participant_id>/<session_id>/pet_linear`.
+Results are stored in the following folder of the [CAPS hierarchy](../CAPS/Specifications.md#pet-imaging-data): `subjects/<participant_id>/<session_id>/pet_linear`.
 
 The main output files are:
 
@@ -100,5 +93,4 @@ You can now use the [ClinicaDL framework](https://clinicadl.readthedocs.io/) pre
     resulting in images of size 169×208×179 with 1 mm isotropic voxels.
 
 !!! tip
-    Easily access the papers cited on this page on
-    [Zotero](https://www.zotero.org/groups/2240070/clinica_aramislab/collections/8AEDUMZB).
+    Easily access the papers cited on this page on [Zotero](https://www.zotero.org/groups/2240070/clinica_aramislab/collections/8AEDUMZB).

docs/Pipelines/PET_Surface.md

@@ -1,8 +1,7 @@
 <!-- markdownlint-disable MD033 MD046 -->
 # `pet-surface` - Surface-based processing of PET images
 
-This pipeline performs several processing steps for the analysis of PET data on the cortical surface
-[[Marcoux et al., 2018](https://doi.org/10.3389/fninf.2018.00094)]:
+This pipeline performs several processing steps for the analysis of PET data on the cortical surface [[Marcoux et al., 2018](https://doi.org/10.3389/fninf.2018.00094)]:
 
 - co-registration of PET and T1-weighted MR images;
 - intensity normalization;
@@ -19,7 +18,7 @@ This pipeline relies mainly on tools from **[FreeSurfer](https://surfer.nmr.mgh.
 
 ## Prerequisite
 
-You need to have performed the [`t1-freesurfer`](../T1_FreeSurfer) pipeline on your T1-weighted MR images.
+You need to have performed the [`t1-freesurfer`](./T1_FreeSurfer.md) pipeline on your T1-weighted MR images.
 
 ## Dependencies
 
@@ -38,13 +37,12 @@ clinica run pet-surface [OPTIONS] BIDS_DIRECTORY CAPS_DIRECTORY ACQ_LABEL
 
 where:
 
-- `BIDS_DIRECTORY` is the input folder containing the dataset in a [BIDS](../../BIDS) hierarchy.
-- `CAPS_DIRECTORY` acts both as an input folder (where the results of the `t1-freesurfer` pipeline are stored) and as the output folder containing the results in a [CAPS](../../CAPS/Introduction) hierarchy.
+- `BIDS_DIRECTORY` is the input folder containing the dataset in a [BIDS](../BIDS.md) hierarchy.
+- `CAPS_DIRECTORY` acts both as an input folder (where the results of the `t1-freesurfer` pipeline are stored) and as the output folder containing the results in a [CAPS](../CAPS/Introduction.md) hierarchy.
 - `ACQ_LABEL` is the label given to the PET acquisition, specifying the tracer used (`trc-<acq_label>`).
 - The reference region is used to perform intensity normalization (i.e. dividing each voxel of the image by the average uptake in this region) resulting in a standardized uptake value ratio (SUVR) map.
-It can be `cerebellumPons` or `cerebellumPons2` (used for amyloid tracers) or `pons` or `pons2` (used for FDG).
-- `PVC_PSF_TSV` is the TSV file containing the `psf_x`, `psf_y` and `psf_z` of the PSF for each PET image. It is expected to be generated by the user.
-More explanation is given in [PET Introduction](../PET_Introduction) page.
+  It can be `cerebellumPons` or `cerebellumPons2` (used for amyloid tracers) or `pons` or `pons2` (used for FDG).
+- `PVC_PSF_TSV` is the TSV file containing the `psf_x`, `psf_y` and `psf_z` of the PSF for each PET image. It is expected to be generated by the user. More explanation is given in [PET Introduction](./PET_Introduction.md) page.
 
 !!! info
     Since the release of Clinica v0.3.8, the handling of PSF information has changed.
@@ -55,8 +53,9 @@ More explanation is given in [PET Introduction](../PET_Introduction) page.
 
 Pipeline options:
 
-- `-np`: This parameter specifies the number of threads to run in parallel.
-We recommend using `your_number_of_cpu - 1`.
+- `--reconstruction_method`: Select only images based on a [specific reconstruction method](./PET_Introduction.md#reconstruction-methods).
+- `-np`: This parameter specifies the number of threads to run in parallel. We recommend using `your_number_of_cpu - 1`.
+
 Please note that PETPVC is extremely demanding in terms of resources and may cause the pipeline to crash if many subjects happen to be partial volume corrected at the same time (Error : `Failed to allocate memory for image`).
 To mitigate this issue, you can do the following:
 
@@ -108,7 +107,7 @@ surface at equal distance between the white matter/gray matter interface and the
 TSV files summarizing the regional statistics on the labelled atlases (Desikan and Destrieux).
 
 !!! note
-    The full list of output files from the `pet-surface` pipeline can be found in [The ClinicA Processed Structure (CAPS) specifications](../../CAPS/Specifications/#pet-surface-surface-based-processing-of-pet-images).
+    The full list of output files from the `pet-surface` pipeline can be found in [The ClinicA Processed Structure (CAPS) specifications](../CAPS/Specifications.md/#pet-surface---surface-based-processing-of-pet-images).
 
 <center>![PET surface results](../img/PET_Surface/PET_Surface.jpg)</center>
 *<center><small>FDG PET SUVR projected onto the cortical surface (left hemisphere) for (from left to right) a cognitively normal subject (CN), a patient with Alzheimer’s disease (AD), a patient with semantic variant primary progressive aphasia (svPPA) and a patient with logopenic variant primary progressive aphasia (lvPPA).
@@ -148,11 +147,6 @@ The second row is the same signal for each subject, but warped to FsAverage afte
     Easily access the papers cited on this page on
     [Zotero](https://www.zotero.org/groups/2240070/clinica_aramislab/items/collectionKey/RGVVHC5W).
 
-## Support
-
-- You can use the [Clinica Google Group](https://groups.google.com/forum/#!forum/clinica-user) to ask for help!
-- Report an issue on [GitHub](https://github.com/aramis-lab/clinica/issues).
-
 ## Appendix I: Diagram of the pipeline execution
 
 <center>![Diagram of the pipeline execution](https://www.frontiersin.org/files/Articles/400789/fninf-12-00094-HTML-r1/image_m/fninf-12-00094-g001.jpg)</center>

docs/Pipelines/PET_Volume.md

@@ -8,15 +8,15 @@ This pipeline performs several processing steps on [PET](../glossary.md#pet) dat
 - inter-subject spatial normalization of the PET image into MNI space based on the DARTEL deformation model of SPM [[Ashburner, 2007](http://dx.doi.org/10.1016/j.neuroimage.2007.07.007)];
 - intensity normalization using the average PET uptake in reference regions resulting in a standardized uptake value ratio ([SUVR](../glossary.md#suvr)) map;
 - parcellation into anatomical regions based on an atlas and computation of average values within each region.
-The list of available atlases can be found [here](../../Atlases).
+The list of available atlases can be found [here](../Atlases.md).
 
 !!! note "Clinica & BIDS specifications for PET modality"
     Since Clinica `v0.6`, PET data following the official specifications in BIDS version 1.6.0 are now compatible with Clinica.
-    See [BIDS](../../BIDS) page for more information.
+    See [BIDS](../BIDS.md) page for more information.
 
 ## Prerequisite
 
-You need to have performed the [`t1-volume`](../T1_Volume) pipeline on your T1-weighted MR images.
+You need to have performed the [`t1-volume`](./T1_Volume.md) pipeline on your T1-weighted MR images.
 
 ## Dependencies
 
@@ -35,18 +35,24 @@ clinica run pet-volume [OPTIONS] BIDS_DIRECTORY CAPS_DIRECTORY GROUP_LABEL ACQ_L
 
 where:
 
-- `BIDS_DIRECTORY` is the input folder containing the dataset in a [BIDS](../../BIDS) hierarchy.
-- `CAPS_DIRECTORY` acts both as an input folder (where the results of the `t1-volume-*` pipeline are stored) and as the output folder containing the results in a [CAPS](../../CAPS/Introduction) hierarchy.
-- `GROUP_LABEL` is the label of the group that is associated to the DARTEL template that you had created when running the [`t1-volume`](../T1_Volume) pipeline.
+- `BIDS_DIRECTORY` is the input folder containing the dataset in a [BIDS](../BIDS.md) hierarchy.
+- `CAPS_DIRECTORY` acts both as an input folder (where the results of the `t1-volume-*` pipeline are stored) and as the output folder containing the results in a [CAPS](../CAPS/Introduction.md) hierarchy.
+- `GROUP_LABEL` is the label of the group that is associated to the DARTEL template that you had created when running the [`t1-volume`](./T1_Volume.md) pipeline.
 - `ACQ_LABEL` is the label given to the PET acquisition, specifying the tracer used (`trc-<acq_label>`).
 - The reference region is used to perform intensity normalization (i.e. dividing each voxel of the image by the average uptake in this region) resulting in a standardized uptake value ratio ([SUVR](../glossary.md#suvr)) map.
 It can be `cerebellumPons` or `cerebellumPons2` (used for amyloid tracers) or `pons` or `pons2` (used for FDG).
 
 Pipeline options:
 
-- `--pvc_psf_tsv`: TSV file containing the `psf_x`, `psf_y` and `psf_z` of the PSF for each PET image.
-More explanation is given in [PET Introduction](../PET_Introduction) page.
+- `--pvc_psf_tsv`: TSV file containing the `psf_x`, `psf_y` and `psf_z` of the PSF for each PET image. More explanation is given in [PET Introduction](./PET_Introduction.md#partial-volume-correction-pvc) page.
 - `--smooth`: a list of integers specifying the different isotropic full width at half maximum ([FWHM](../glossary.md#fwhm)) in millimeters to smooth the image. Default value is: 0, 8 (both without smoothing and with an isotropic smoothing of 8 mm)
+- `--reconstruction_method`: Select only images based on a [specific reconstruction method](./PET_Introduction.md#reconstruction-methods).
+
+!!! warning
+    It can happen that a [BIDS](../BIDS.md) dataset contains several [PET](../glossary.md#pet) scans for a given subject and session.
+    In this situation, these images will differ through at least one [BIDS](../BIDS.md) entity like the tracer or the reconstruction method.
+    When running the `pet-volume` pipeline, clinica will raise an error if more than one image matches the criteria provided through the command line.
+    To avoid that, it is important to specify values for these options such that a single image is selected per subject and session.
 
 !!! info
     Since the release of Clinica v0.3.8, the handling of PSF information in the TSV file has changed: `fwhm_x`, `fwhm_y`, `fwhm_z` columns have been replaced by `psf_x`, `psf_y`, `psf_z` and the `acq_label` column has been added.
@@ -61,9 +67,7 @@ More explanation is given in [PET Introduction](../PET_Introduction) page.
 
 ## Outputs
 
-Results are stored in the following folder of the
-[CAPS hierarchy](../../CAPS/Specifications/#pet-volume-volume-based-processing-of-pet-images):
-`subjects/<participant_id>/<session_id>/pet/preprocessing`.
+Results are stored in the following folder of the [CAPS hierarchy](../CAPS/Specifications.md#pet-volume---volume-based-processing-of-pet-images): `subjects/<participant_id>/<session_id>/pet/preprocessing`.
 
 The main output files are:
 
@@ -108,8 +112,3 @@ The main output files are:
 
 !!! tip
     Easily access the papers cited on this page on [Zotero](https://www.zotero.org/groups/2240070/clinica_aramislab/items/collectionKey/INDXD9QQ).
-
-## Support
-
-- You can use the [Clinica Google Group](https://groups.google.com/forum/#!forum/clinica-user) to ask for help!
-- Report an issue on [GitHub](https://github.com/aramis-lab/clinica/issues).