📝 Document "🐛 Allow specifying any ROI paths, including or excluding defaults" (#254)

shnizzedy · web-flow · commit 3784026b322a · 2021-09-17T16:57:38.000-04:00
diff --git a/docs/_sources/user/alff.rst b/docs/_sources/user/alff.rst
@@ -37,10 +37,7 @@ Configuring CPAC to Run ALFF and f/ALFF
 
 #. **f/ALFF Low-Pass Cutoff - [decimal]:** Frequency cutoff (in Hz) for the low-pass filter used when calculating f/ALFF
 
-Configuration Without the GUI
-""""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
diff --git a/docs/_sources/user/anat.rst b/docs/_sources/user/anat.rst
@@ -17,10 +17,7 @@ Configuring CPAC to run surface analysis:
 
 #. **FreeSurfer - [On,Off]:** FreeSurfer recon-all. Default is Off.
 
-Configuration Without the GUI
-""""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
@@ -49,10 +46,7 @@ Configuring CPAC to run initial preprocessing:
 
 #. **N4 Bias Field Correction - [On,Off]:** ANTs N4BiasFieldCorrection - a variant of the popular N3 (nonparametric nonuniform normalization) retrospective bias correction algorithm. Default is Off.
 
-Configuration Without the GUI
-""""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
@@ -68,10 +62,7 @@ Configuring ACPC Alignment options:
 #. **ACPC Aligned Skull Template - [path]:** Skull template to be used for ACPC alignment. It is not necessary to change this path unless you intend to use a non-standard template.
 #. **ACPC Aligned Brain Template - [path]:** Brain template to be used for ACPC alignment. For human data, it can be 'None'. It is not necessary to change this path unless you intend to use a non-standard template.
 
-Configuration Without the GUI
-""""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
@@ -100,10 +91,7 @@ Configuring CPAC to run Skull-Stripping:
 
 #. **Which tool for skull-stripping - [FSL, AFNI, niworkflows-ants]:** Choose if you’d like to use FSL BET, AFNI 3dSkullStrip, or run all options in parallel.
 
-Configuration Without the GUI
-""""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
@@ -151,10 +139,7 @@ Configuring AFNI 3dSkullStrip options:
 
 #. **blur_fwhm - [2]:** Blur datasets after spatial normalization. Default value is 2.
 
-Configuration Without the GUI
-""""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
@@ -192,10 +177,7 @@ Configuring FSL BET options:
 
 #. **Robust brain center - [Off, On]:** Robust brain center estimation. Mutually exclusive with functional, reduce_bias, robust, padding, remove_eyes, surfaces.
 
-Configuration Without the GUI
-""""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
@@ -213,10 +195,7 @@ Configuring niworkflows-ants options:
 
 #. **niworkflows_ants_regmask_path:** Set the brain extraction registration mask, used for registration to limit the metric computation to a specific region. e.g. OASIStemplate/T_template0_BrainCerebellumRegistrationMask.nii.gz
 
-Configuration Without the GUI
-""""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
@@ -260,10 +239,7 @@ Configuring CPAC to Run Anatomical Registration
 
 #. **Interpolation Method - [trilinear, sinc, spline]:** Interpolation method for writing out transformed anatomical images. FSL registration tools only. Options are trilinear, sinc, or spline.
 
-Configuration Without the GUI
-"""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
@@ -364,10 +340,7 @@ Configuring CPAC to Run Anatomical Tissue Segmentation
 #. **Right White Matter Label Value - [integer]:** Label value corresponding to Right White Matter in multiatlas file. It is not necessary to change this values unless your CSF/GM/WM label values are different from `Freesurfer Color Lookup Table. <https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/AnatomicalROI/FreeSurferColorLUT>`_
 
 
-Configuration Without the GUI
-"""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
diff --git a/docs/_sources/user/centrality.rst b/docs/_sources/user/centrality.rst
@@ -57,10 +57,7 @@ Configuring C-PAC to Run Network Centrality
 
 Note that only centrality measures that have binarized/weighted checked on this screen will be run.
 
-Configuration Without the GUI
-""""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
diff --git a/docs/_sources/user/compute_config.rst b/docs/_sources/user/compute_config.rst
@@ -24,10 +24,7 @@ Computer Settings
 
 #. **SGE Queue - [text]:** SGE Queue to use when running CPAC. Only applies when you are running on a grid or compute cluster using SGE.  See the section below entitled `SGE Configuration` for more information on how to set up SGE.
 
-Configuration Without the GUI
-""""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
diff --git a/docs/_sources/user/func.rst b/docs/_sources/user/func.rst
@@ -32,9 +32,7 @@ Initial Preprocessing
 
 .. _func_init_without_gui:
 
-Configuration Without the GUI
-"""""""""""""""""""""""""""""
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
@@ -76,10 +74,7 @@ You can configure your slice time correction settings through the C-PAC pipeline
 
 Note that if a scan parameters file was used to construct the participant list, the parameters defined in this file will override the settings used here.
 
-Configuration Without the GUI
-"""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
@@ -162,10 +157,7 @@ The C-PAC pipeline configuration builder provides options for configuring the Di
 
 #. **Phase encoding direction - [string]:** This is the position of the voxels in the input image, and can have values of x/y/z or -x/-y/-z.
 
-Configuration Without the GUI
-"""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
@@ -187,10 +179,7 @@ Functional to Anatomical Registration
 
 #. **Functional Masking - [AFNI, FSL, FSL_AFNI, Anatomical_Refined]:** Choose which tool to be used in functional masking - AFNI (3dAutoMask), FSL (BET), FSL_AFNI (BET+3dAutoMask) or Anatomical_Refined (generate functional mask by registering anatomical mask to functional space). Default is AFNI.
 
-Configuration Without the GUI
-"""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
@@ -231,11 +220,7 @@ Configuring FSL BET options:
 
 #. **Robust brain center - [Off, On]:** Robust brain center estimation. Mutually exclusive with functional, reduce_bias, robust, padding, remove_eyes, surfaces.
 
-
-Configuration Without the GUI
-"""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
@@ -265,10 +250,7 @@ Functional to Template Registration
 
 #. **ANTs Registration Parameters :** Clicking on the setting icon will bring up a dialog where you can set 'antsRegistration' parameters.
 
-Configuration Without the GUI
-"""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
diff --git a/docs/_sources/user/futuredocs/epi_distcorr.rst b/docs/_sources/user/futuredocs/epi_distcorr.rst
@@ -11,10 +11,7 @@ The parameters provided in the GUI are described below:
 6. Dwell to asymmetric ratio-[float]: This is the ratio between the Dwell time, as referenced above and the asymmetric time. Here, the default value is 0.93902439.
 7. Phase encoding direction-[string]: This is the position of the voxels in the input image, and can have values of x/y/z or -x/-y/-z. This is predominantly a trail and error based parameter.
 
-Configuration without the GUI
-"""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
diff --git a/docs/_sources/user/longitudinal.rst b/docs/_sources/user/longitudinal.rst
@@ -22,10 +22,7 @@ Configuring CPAC to Run Longitudinal Preprocessing Pipeline
 #. **Thread Pool - [integer]:**  Number of threads in a thread pool. More threads can speed up the longitudinal template creation process. Default is 2.
 #. **Convergence Threshold - [integer]:** Convergence threshold of longitudinal template. Default is -1, which uses numpy.finfo(np.float64).eps.
 
-Configuration Without the GUI
-"""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
diff --git a/docs/_sources/user/nuisance.rst b/docs/_sources/user/nuisance.rst
@@ -129,10 +129,7 @@ Configuring Temporal Filtering Options
 
 .. _nuisance-no-gui:
 
-Configuration Without the GUI
-"""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
diff --git a/docs/_sources/user/output_config.rst b/docs/_sources/user/output_config.rst
@@ -31,10 +31,7 @@ Output Settings
 
 #. **Enable Quality Control Interface - [On, Off]:** Generate quality control pages containing preprocessing and derivative outputs.
 
-Configuration Without the GUI
-""""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
diff --git a/docs/_sources/user/pipelines/design_a_pipeline.rst b/docs/_sources/user/pipelines/design_a_pipeline.rst
@@ -1,7 +1,7 @@
 Design A Pipeline
 -----------------
 
-.. warning::
+.. note::
 
     The C-PAC pipeline configuration was changed to a nested format with import capabilities in v1.8.0.
     
diff --git a/docs/_sources/user/pipelines/pipeline_config.rst b/docs/_sources/user/pipelines/pipeline_config.rst
@@ -36,6 +36,7 @@ Definitions
 * Template
     .. include:: /glossary/template.rst
         :start-line: 3
+
 .. rubric:: Reference
 
 .. bibliography:: /references/glossary.bib
@@ -75,7 +76,7 @@ Pipeline configuration files, like the data settings and data configuration file
    :language: YAML
    :lines: 10-51
 
-An example of a pipeline configuration YAML file can be found :doc:`here </user/pipelines/default>`.  Tables explaining the keys and their potential values can be found on the individual pages for each of the outputs C-PAC is capable of producing. All pipeline setup configuration files should have the keys in the :doc:`Output Settings </user/output_config>`_ table defined.
+An example of a pipeline configuration YAML file can be found :doc:`here </user/pipelines/default>`.  Tables explaining the keys and their potential values can be found on the individual pages for each of the outputs C-PAC is capable of producing. All pipeline setup configuration files should have the keys in the :doc:`Output Settings </user/output_config>` table defined.
 
 String values can include the simplest form of `POSIX parameter expansion <https://pubs.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_06_02>` (``${parameter}``). Two special variables are included for these types of parameters:
 
@@ -93,7 +94,7 @@ If ``FROM`` is defined (see above), any undefined keys will be inferred from the
 
 Why a list?
 '''''''''''
-You may notice as you learn about the settings for various outputs that many of the values for C-PAC's configurable settings are stored in lists (i.e., multiple values are separated by commas and surrounded by square brackets).  Such lists containing 1s and 0s (for 'True' and 'False' respectively) allow you to toggle on multiple options at the same time, and branch a pipeline into two different analysis strategies. See the `developer documentation <http://fcp-indi.github.io/docs/developer/workflows/cpac_pipeline.html>`_ for more information about how lists are used in C-PAC.
+You may notice as you learn about the settings for various outputs that many of the values for C-PAC's configurable settings are stored in lists (i.e., multiple values are separated by commas and surrounded by square brackets).  Such lists containing ``On``s and ``Off``s (for ``True`` and ``False`` respectively) allow you to toggle on multiple options at the same time, and branch a pipeline into two different analysis strategies. See the `developer documentation <http://fcp-indi.github.io/docs/developer/workflows/cpac_pipeline.html>`_ for more information about how lists are used in C-PAC.
 
 Configurable Settings
 ------------------------------
diff --git a/docs/_sources/user/pipelines/without_gui.rst b/docs/_sources/user/pipelines/without_gui.rst
@@ -0,0 +1,4 @@
+Configuration Without the GUI
+""""""""""""""""""""""""""""""
+
+The following nested key/value pairs will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`.
diff --git a/docs/_sources/user/pypeer.rst b/docs/_sources/user/pypeer.rst
@@ -24,10 +24,7 @@ Configuring CPAC to Run PyPEER
 
 #. **Motion Scrubbing Threshold:** The threshold for motion (in mm) to use for motion scrubbing, if it is selected. PyPEER employs the Power (2012) measurement for framewise displacement.
 
-Configuration Without the GUI
-""""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
diff --git a/docs/_sources/user/reho.rst b/docs/_sources/user/reho.rst
@@ -31,10 +31,7 @@ Configuring CPAC to Run ReHo
 
 #. **Voxel Cluster Size - [7,19,27]:** Number of neighboring voxels used when calculating ReHo. 7 (Faces), 19 (Faces + Edges), or 27 (Faces + Edges + Corners).
 
-Configuration Without the GUI
-""""""""""""""""""""""""""""""
-
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/pipelines/without_gui.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
diff --git a/docs/_sources/user/roi_paths.rst b/docs/_sources/user/roi_paths.rst
@@ -0,0 +1,15 @@
+Unlike most lines in a C-PAC pipeline configuration file, the keys under ``*_roi_paths`` are user-definable.
+
+If you exclude ``*_roi_paths`` from your pipeline configuration, the default atlases and analyses will be used.
+
+If you include ``*_roi_paths``, **only the atlases and analyses provided** will be used, unless you add the optional key/value pair ``roi_paths_fully_specified: False`` in the relevant section, in which case the default atlases and analyses will be updated with the atlases and analyses specified in your pipeline config. For example,
+
+.. code-block:: yaml
+
+    timeseries_extraction:
+        roi_paths_fully_specified: False
+
+    seed_based_correlation_analysis:
+        roi_paths_fully_specified: False
+
+would keep any default atlases not respecified in your pipeline configuration.
diff --git a/docs/_sources/user/sca.rst b/docs/_sources/user/sca.rst
@@ -47,10 +47,9 @@ Before SCA can be calculated, you **must** first extract a seed time series from
 
 #. **Normalize Time Series (Dual Regression) - [On, Off]:**  Normalize each time series before running Dual Regression.
 
-Configuration Without the GUI
-""""""""""""""""""""""""""""""
+.. include:: /user/pipelines/without_gui.rst
 
-The following nested key/value pairs that will be set to these defaults if not defined in your :doc:`pipeline configuration YAML </user/pipelines/pipeline_config>`:
+.. include:: /user/roi_paths.rst
 
 .. literalinclude:: /references/default_pipeline.yml
    :language: YAML
diff --git a/docs/_sources/user/tse.rst b/docs/_sources/user/tse.rst
diff --git a/docs/_sources/user/vmhc.rst b/docs/_sources/user/vmhc.rst
