[DOC] Move repeated blocks of documentation in snippets for pipelines (…

…#1456)

* Add center-nifti issue to snippets

* Fix snippet

* Reorganize options for some pipelines

* Test for options snippet

* Modify pipelines options snippet

* Option PVC

* Fix block

* Fix block2

* Fix block3

* Modify linear options

* Add inputs as snippets

* Add inputs as snippets in pipelines

* Buffer error

* Change as suggested

* Add warning

docs/Pipelines/DWI_Connectome.md

@@ -22,9 +22,10 @@ clinica run dwi-connectome [OPTIONS] CAPS_DIRECTORY
 
 where:
 
-- `CAPS_DIRECTORY` is the input/output folder containing the results in a [CAPS](../CAPS/Introduction.md) hierarchy.
+--8<-- "snippets/cmd_inputs.md:caps"
 
-If you want to run the pipeline on a subset of your [CAPS](../CAPS/Introduction.md) dataset, you can use the `-tsv` flag to specify in a [TSV](../glossary.md#tsv) file the participants belonging to your subset.
+??? info "Optional parameters common to all pipelines"
+    --8<-- "snippets/pipelines_options.md:all"
 
 !!! note "Number of streamlines (`--n_tracks` option)"
     The quality of the tractography and, as a result, the connectome mainly depends on the number of streamlines you can generate (the more the better).

docs/Pipelines/DWI_DTI.md

@@ -24,9 +24,10 @@ clinica run dwi-dti CAPS_DIRECTORY
 
 where:
 
-- `CAPS_DIRECTORY` is the input/output folder containing the results in a [CAPS](../../CAPS/Introduction) hierarchy.
+--8<-- "snippets/cmd_inputs.md:caps"
 
-If you want to run the pipeline on a subset of your CAPS dataset, you can use the `-tsv` flag to specify in a TSV file the participants belonging to your subset.
+??? info "Optional parameters common to all pipelines"
+    --8<-- "snippets/pipelines_options.md:all"
 
 ## Outputs
 

docs/Pipelines/DWI_Preprocessing.md

@@ -40,19 +40,16 @@ clinica run dwi-preprocessing-using-phasediff-fmap [OPTIONS] BIDS_DIRECTORY CAPS
 
 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.
+--8<-- "snippets/cmd_inputs.md:bids_caps"
 
 Please note that you will need the `PhaseEncodingDirection` and `TotalReadoutTime` metadata fields in the JSON file associated to your DWI images
 (see [BIDS specifications](https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#diffusion-imaging-data) for more details).
 For the `dwi-preprocessing-using-phasediff-fmap`pipeline, you will also need the  `EchoTime1` and `EchoTime2` metadata fields in the JSON file associated to your fieldmap images
 (see [BIDS specifications](https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#phase-difference-image-and-at-least-one-magnitude-image)).
 Without these metadata fields, the pipelines will not run.
 
-If you want to run the pipeline on a subset of your BIDS dataset, you can use the `-tsv` flag to specify in a TSV file the participants belonging to your subset.
-
-It is possible to specify the name of the CAPS dataset that will be created to store the outputs of the pipeline. This works if this CAPS dataset does not exist yet, otherwise the existing name will be kept.
-This can be achieved with the `--caps-name` option. The provided name will appear in the `dataset_description.json` file, at the root of the CAPS folder (see [CAPS Specifications](../CAPS/Specifications.md#the-dataset_descriptionjson-file) for more details).
+??? info "Optional parameters common to all pipelines"
+    --8<-- "snippets/pipelines_options.md:all"
 
 !!! tip "Decreasing computation time"
     By default, the `eddy` tool of FSL uses OpenMP for parallel computing.

docs/Pipelines/FLAIR_Linear.md

@@ -30,18 +30,15 @@ clinica run flair-linear [OPTIONS] BIDS_DIRECTORY CAPS_DIRECTORY
 
 where:
 
-- `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.
+--8<-- "snippets/cmd_inputs.md:bids_caps"
 
 with specific options : 
 
-- `-ui`/`--uncropped_image` : By default, output images are cropped to a **fixed** matrix size of 169×208×179, 1 mm isotropic voxels. This allows reducing the computing power required when training deep learning models afterwards.
-Use this option if you do not want to get cropped images.
-- `--random_seed` : By default, results are not deterministic. Use this option if you want to obtain a deterministic output. The value you set corresponds to the random seed used by ANTs. This option requires [ANTs](../Software/Third-party.md#ants) version `2.3.0` onwards and is also compatible with [ANTsPy](https://antspyx.readthedocs.io/en/latest/index.html).
-- `--use-antspy` : By default, the pipeline is running with [ANTs](../Software/Third-party.md#ants). Use this flag option if you want to use [ANTsPy](https://antspyx.readthedocs.io/en/latest/index.html) instead.
+--8<-- "snippets/pipelines_options.md:linear"
+--8<-- "snippets/pipelines_options.md:antspy"
 
 ??? info "Optional parameters common to all pipelines"
-    --8<-- "snippets/pipelines_options.md"
+    --8<-- "snippets/pipelines_options.md:all"
 
 !!! tip
     Do not hesitate to type `clinica run flair-linear --help` to see the full list of parameters.

docs/Pipelines/PET_Linear.md

@@ -33,28 +33,20 @@ 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.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.
+--8<-- "snippets/cmd_inputs.md:bids_caps"
+--8<-- "snippets/cmd_inputs.md:acq"
+--8<-- "snippets/cmd_inputs.md:region"
 
-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.
+with specific options :
 
-It is possible to select only images based on a [specific reconstruction method](./PET_Introduction.md#reconstruction-methods) with the `--reconstruction_method` option.
+--8<-- "snippets/pipelines_options.md:linear"
+--8<-- "snippets/pipelines_options.md:pet_recon"
+- `--save_pet_in_t1w_space`: Use this option to save the [PET](../glossary.md#pet) image in the T1w space after rigid transformation.
 
-!!! 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.
+??? info "Optional parameters common to all pipelines"
+    --8<-- "snippets/pipelines_options.md:all"
 
-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](../Software/InteractingWithClinica.md).
+--8<-- "snippets/known_issues.md:several_pet"
 
 !!! tip
     Do not hesitate to type `clinica run pet-linear --help` to see the full list of parameters.

docs/Pipelines/PET_Surface.md

@@ -37,62 +37,31 @@ 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.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)](../glossary.md#suvr) map. It can be `cerebellumPons` or `cerebellumPons2` (used for amyloid tracers) or `pons` or `pons2` (used for FDG).
+--8<-- "snippets/cmd_inputs.md:bids_caps"
+--8<-- "snippets/cmd_inputs.md:acq"
+--8<-- "snippets/cmd_inputs.md:region"
 - `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 "Clinica v0.3.8+"
+        Since the release of Clinica v0.3.8, the handling of PSF information has changed.
+        In previous versions of Clinica, each BIDS-PET image had to contain a JSON file with the `EffectiveResolutionInPlane` and `EffectiveResolutionAxial` fields corresponding to the PSF in mm.
+        `EffectiveResolutionInPlane` is replaced by both `psf_x` and `psf_y`, `EffectiveResolutionAxial` is replaced by `psf_z` and the `acq_label` column has been added.
+        Additionally, the SUVR reference region is now a compulsory argument: it will be easier for you to modify Clinica if you want to add a custom reference region ([PET Introduction](../PET_Introduction) page).
+        Choose `cerebellumPons` for amyloid tracers or `pons` for FDG to have the previous behavior.
 
-!!! warning "Centering BIDS nifti"
-    The intra-subject registration of the PET image into the space of the subject’s T1-weighted MR image is very likely to fail if the images have important relative offsets.
-    In this situation, Clinica will give a warning displaying a command that should be run in order to generate a new BIDS directory with all images centered.
-    This relies on the IOTool [center-nifti](../IOTools/center_nifti.md).
-    It is highly recommended to follow this recommendation but Clinica won't force you to do so.
+with specific options : 
 
-!!! info
-    Since the release of Clinica v0.3.8, the handling of PSF information has changed.
-    In previous versions of Clinica, each BIDS-PET image had to contain a JSON file with the `EffectiveResolutionInPlane` and `EffectiveResolutionAxial` fields corresponding to the PSF in mm.
-    `EffectiveResolutionInPlane` is replaced by both `psf_x` and `psf_y`, `EffectiveResolutionAxial` is replaced by `psf_z` and the `acq_label` column has been added.
-    Additionally, the SUVR reference region is now a compulsory argument: it will be easier for you to modify Clinica if you want to add a custom reference region ([PET Introduction](../PET_Introduction) page).
-    Choose `cerebellumPons` for amyloid tracers or `pons` for FDG to have the previous behavior.
+- `-rec/--reconstruction_method`: Select only images based on a [specific reconstruction method](./PET_Introduction.md#reconstruction-methods).
 
-Pipeline options:
+??? info "Optional parameters common to all pipelines"
+    --8<-- "snippets/pipelines_options.md:all"
 
-- `--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:
-
-    **1)** Use a working directory when you launch Clinica.
-
-    **2)** If the pipeline crashed, just launch again the command (while giving the same working directory).
-    The whole processing will continue where it left (you can reduce the number of threads to run in parallel the second time).
-
-!!! note
-    The arguments common to all Clinica pipelines are described in [Interacting with clinica](../../InteractingWithClinica).
+--8<-- "snippets/known_issues.md:petpvc"
 
 !!! tip
     Do not hesitate to type `clinica run pet-surface --help` to see the full list of parameters.
 
-!!! failure "Known error on macOS"
-    If you are running `pet-surface` on macOS, we noticed that if the path to the CAPS is too long, the pipeline fails when the `gtmseg` command from FreeSurfer is executed.
-    This generates crash files with `gtmseg` in the filename, for instance:
-
-    ```console
-    $ nipypecli crash crash-20210404-115414-sheldon.cooper-gtmseg-278e3a57-294f-4121-8a46-9975801f24aa.pklz
-    [...]
-    Abort
-    ERROR: mri_gtmseg --s sub-ADNI011S4105_ses-M000 --usf 2 --o gtmseg.mgz --apas apas+head.mgz --no-subseg-wm --no-keep-cc --no-keep-hypo
-    gtmseg exited with errors
-    Standard error:
-    Saving result to '<caps>/subjects/sub-ADNI011S4105/ses-M000/t1/freesurfer_cross_sectional/sub-ADNI011S4105_ses-M000/tmp/tmpdir.xcerebralseg.50819/tmpdir.fscalc.53505/tmp.mgh' (type = MGH )                       [ ok ]
-    Saving result to '<caps>/subjects/sub-ADNI011S4105/ses-M000/t1/freesurfer_cross_sectional/sub-ADNI011S4105_ses-M000/tmp/tmpdir.xcerebralseg.50819/tmpdir.fscalc.53727/tmp.mgh' (type = MGH )                       [ ok ]
-    Saving result to '<caps>/subjects/sub-ADNI011S4105/ses-M000/t1/freesurfer_cross_sectional/sub-ADNI011S4105_ses-M000/tmp/tmpdir.xcerebralseg.50819/tmpdir.fscalc.53946/tmp.mgh' (type = MGH )                       [ ok ]
-    Return code: 1
-    ```
-
-    This is under investigation (see [Issue #119](https://github.com/aramis-lab/clinica/issues/119) for details) and will be solved as soon as possible.
+--8<-- "snippets/known_issues.md:gtmseg"
 
 ## Outputs
 

docs/Pipelines/PET_Surface_Longitudinal.md

@@ -43,60 +43,28 @@ clinica run pet-surface-longitudinal [OPTIONS] BIDS_DIRECTORY CAPS_DIRECTORY ACQ
 
 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-longitudinal` pipeline are stored) and
-as 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>`).
-- 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).
+--8<-- "snippets/cmd_inputs.md:bids_caps"
+--8<-- "snippets/cmd_inputs.md:acq"
+--8<-- "snippets/cmd_inputs.md:region"
 - `PVC_PSF_TSV` is the 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.
 
-!!! info
-    Since the release of Clinica v0.3.8, the handling of PSF information has changed.
-    In previous versions of Clinica, each BIDS-PET image had to contain a JSON file with the `EffectiveResolutionInPlane` and `EffectiveResolutionAxial` fields corresponding to the PSF in mm.
-    `EffectiveResolutionInPlane` is replaced by both `psf_x` and `psf_y`, `EffectiveResolutionAxial` is replaced by `psf_z` and the `acq_label` column has been added.
-    Additionally, the SUVR reference region is now a compulsory argument: it will be easier for you to modify Clinica if you want to add a custom reference region ([PET Introduction](../PET_Introduction) page).
-    Choose `cerebellumPons` for amyloid tracers or `pons` for FDG to have the previous behavior.
+    ??? info "Clinica v0.3.8+"
+        Since the release of Clinica v0.3.8, the handling of PSF information has changed. In previous versions of Clinica, each BIDS-PET image had to contain a JSON file with the 
+        `EffectiveResolutionInPlane` and `EffectiveResolutionAxial` fields corresponding to the PSF in mm. `EffectiveResolutionInPlane` is replaced by both `psf_x` and `psf_y`,
+        `EffectiveResolutionAxial` is replaced by `psf_z` and the `acq_label` column has been added. Additionally, the SUVR reference region is now a compulsory argument:
+        it will be easier for you to modify Clinica if you want to add a custom reference region ([PET Introduction](../PET_Introduction) page). Choose `cerebellumPons` for amyloid tracers or `pons` for FDG to have the previous behavior.
 
-Pipeline options:
+
+??? info "Optional parameters common to all pipelines"
+    --8<-- "snippets/pipelines_options.md:all"
 
-- `-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:
-
-    **1)** Use a working directory when you launch Clinica.
-
-    **2)** If the pipeline crashed, just launch again the command (while giving the same working directory).
-    The whole processing will continue where it left (you can reduce the number of threads to run in parallel the second time).
-
-!!! note
-    The arguments common to all Clinica pipelines are described in [Interacting with Clinica](../../InteractingWithClinica).
+--8<-- "snippets/known_issues.md:petpvc"
 
 !!! tip
     Do not hesitate to type `clinica run pet-surface-longitudinal --help` to see the full list of parameters.
 
-!!! failure "Known error on macOS"
-    If you are running `pet-surface-longitudinal` on macOS, we noticed that if the path to the CAPS is too long, the pipeline fails when the `gtmseg` command from FreeSurfer is executed.
-    This generates crash files with `gtmseg` in the filename, for instance:
-
-    ```console
-    $ nipypecli crash crash-20210404-115414-sheldon.cooper-gtmseg-278e3a57-294f-4121-8a46-9975801f24aa.pklz
-    [...]
-    Abort
-    ERROR: mri_gtmseg --s sub-ADNI011S4105_ses-M000 --usf 2 --o gtmseg.mgz --apas apas+head.mgz --no-subseg-wm --no-keep-cc --no-keep-hypo
-    gtmseg exited with errors
-    Standard error:
-    Saving result to '<caps>/subjects/sub-ADNI011S4105/ses-M000/t1/freesurfer_cross_sectional/sub-ADNI011S4105_ses-M000/tmp/tmpdir.xcerebralseg.50819/tmpdir.fscalc.53505/tmp.mgh' (type = MGH )                       [ ok ]
-    Saving result to '<caps>/subjects/sub-ADNI011S4105/ses-M000/t1/freesurfer_cross_sectional/sub-ADNI011S4105_ses-M00/tmp/tmpdir.xcerebralseg.50819/tmpdir.fscalc.53727/tmp.mgh' (type = MGH )                       [ ok ]
-    Saving result to '<caps>/subjects/sub-ADNI011S4105/ses-M000/t1/freesurfer_cross_sectional/sub-ADNI011S4105_ses-M000/tmp/tmpdir.xcerebralseg.50819/tmpdir.fscalc.53946/tmp.mgh' (type = MGH )                       [ ok ]
-    Return code: 1
-    ```
-
-    This is under investigation (see [Issue #119](https://github.com/aramis-lab/clinica/issues/119) for details) and will be solved as soon as possible.
+--8<-- "snippets/known_issues.md:gtmseg"
 
 !!! warning "Case where several longitudinal IDs are present"
     If a subject has more than two longitudinal IDs (e.g. `long-M000M018` and `long-M000M018M036`),