DOC: Update docs following read-through (#2930)

## Changes proposed in this pull request This PR goes through all of the documentation except for the API docs. I have made sure that all workflow graphs are generated, but not that the docstrings match the function signatures. I did add type annotations to the `init_*_wf()` functions to improve that, at least. This is pretty wide-ranging and addresses all warnings from Sphinx. This does not change the theme, as the [sphinx-immaterial](https://jbms.github.io/sphinx-immaterial) theme I was considering made the API page unusable. That should be done more thoughtfully in a separate PR. ## Documentation that should be reviewed All of it.
nipreps · Jan 26, 2023 · 689ad26 · 689ad26
2 parents 02b8d2d + 54410e8
commit 689ad26
Show file tree

Hide file tree

Showing 26 changed files with 2,029 additions and 2,196 deletions.
diff --git a/README.rst b/README.rst
@@ -42,10 +42,10 @@ state-of-the-art interface that is robust to variations in scan acquisition
 protocols and that requires minimal user input, while providing easily
 interpretable and comprehensive error and output reporting.
 It performs basic processing steps (coregistration, normalization, unwarping,
-noise component extraction, segmentation, skullstripping etc.) providing
+noise component extraction, segmentation, skull-stripping, etc.) providing
 outputs that can be easily submitted to a variety of group level analyses,
-including task-based or resting-state fMRI, graph theory measures, surface or
-volume-based statistics, etc.
+including task-based or resting-state fMRI, graph theory measures, and surface
+or volume-based statistics.
 
 .. note::
 
@@ -71,7 +71,7 @@ This tool allows you to easily do the following:
 - Receive verbose output concerning the stage of preprocessing for each
   subject, including meaningful errors.
 - Automate and parallelize processing steps, which provides a significant
-  speed-up from typical linear, manual processing.
+  speed-up from manual processing or shell-scripted pipelines.
 
 More information and documentation can be found at
 https://fmriprep.readthedocs.io/

diff --git a/docs/_static/brainextraction.svg b/docs/_static/brainextraction.svg
diff --git a/docs/_static/brainextraction_t1.svg b/docs/_static/brainextraction_t1.svg
diff --git a/docs/_static/sub-01_dseg.svg b/docs/_static/sub-01_dseg.svg
diff --git a/docs/_static/sub-01_task-balloonanalogrisktask_run-1_desc-rois_bold.svg b/docs/_static/sub-01_task-balloonanalogrisktask_run-1_desc-rois_bold.svg
diff --git a/docs/faq.rst b/docs/faq.rst
@@ -205,23 +205,23 @@ will be used.
 Finally, both the ``--cifti-output`` and ``--use-aroma`` arguments require ``MNI152NLin6Asym``.
 To do so, follow the next steps.
 
-  1. By default, a mirror of *TemplateFlow* to store the resources will be
-     created in ``$HOME/.cache/templateflow``.
-     You can modify such a configuration with the ``TEMPLATEFLOW_HOME``
-     environment variable, e.g.::
+1. By default, a mirror of *TemplateFlow* to store the resources will be
+   created in ``$HOME/.cache/templateflow``.
+   You can modify such a configuration with the ``TEMPLATEFLOW_HOME``
+   environment variable, e.g.::
 
-       $ export TEMPLATEFLOW_HOME=$HOME/.templateflow
+     $ export TEMPLATEFLOW_HOME=$HOME/.templateflow
 
-  2. Install the client within your favorite Python 3 environment (this can
-     be done in your login-node, or in a host with Internet access,
-     without need for Docker/Singularity)::
+2. Install the client within your favorite Python 3 environment (this can
+   be done in your login-node, or in a host with Internet access,
+   without need for Docker/Singularity)::
 
-       $ python -m pip install -U templateflow
+     $ python -m pip install -U templateflow
 
-  3. Use the ``get()`` utility of the client to pull down all the templates you'll
-     want to use. For example::
+3. Use the ``get()`` utility of the client to pull down all the templates you'll
+   want to use. For example::
 
-       $ python -c "from templateflow.api import get; get(['MNI152NLin2009cAsym', 'MNI152NLin6Asym', 'OASIS30ANTs', 'MNIPediatricAsym', 'MNIInfant'])"
+     $ python -c "from templateflow.api import get; get(['MNI152NLin2009cAsym', 'MNI152NLin6Asym', 'OASIS30ANTs', 'MNIPediatricAsym', 'MNIInfant'])"
 
 After getting the resources you'll need, you will just need to make sure your
 runtime environment is able to access the filesystem, at the location of your
@@ -287,17 +287,17 @@ across sessions.
 When substantial changes are expected, special considerations must be taken.
 Some examples follow:
 
-  * Surgery: use only pre-operation sessions for the anatomical data. This will typically be done
-    by omitting post-operation sessions from the inputs to *fMRIPrep*.
-  * Developing and elderly populations: there is currently no standard way of processing these.
-    However, `as suggested by U. Tooley at NeuroStars.org
-    <https://neurostars.org/t/fmriprep-how-to-reuse-longitudinal-and-pre-run-freesurfer/4585/15>`__,
-    it is theoretically possible to leverage the *anatomical fast-track* along with the
-    ``--bids-filters`` option to process sessions fully independently, or grouped by some study-design
-    criteria.
-    Please check the `link
-    <https://neurostars.org/t/fmriprep-how-to-reuse-longitudinal-and-pre-run-freesurfer/4585/15>`__
-    for further information on this approach.
+* Surgery: use only pre-operation sessions for the anatomical data. This will typically be done
+  by omitting post-operation sessions from the inputs to *fMRIPrep*.
+* Developing and elderly populations: there is currently no standard way of processing these.
+  However, `as suggested by U. Tooley at NeuroStars.org
+  <https://neurostars.org/t/fmriprep-how-to-reuse-longitudinal-and-pre-run-freesurfer/4585/15>`__,
+  it is theoretically possible to leverage the *anatomical fast-track* along with the
+  ``--bids-filters`` option to process sessions fully independently, or grouped by some study-design
+  criteria.
+  Please check the `link
+  <https://neurostars.org/t/fmriprep-how-to-reuse-longitudinal-and-pre-run-freesurfer/4585/15>`__
+  for further information on this approach.
 
 
 How to decrease *fMRIPrep* runtime when working with large datasets?

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -3,29 +3,27 @@
 ------------
 Installation
 ------------
-There are two ways to get *fMRIPrep* installed:
+There are two ways to install *fMRIPrep*:
 
-* within a `Manually Prepared Environment (Python 3.7+)`_, also known as
-  *bare-metal installation*; or
-* using container technologies (RECOMMENDED).
+* using container technologies (RECOMMENDED); or
+* within a `Manually Prepared Environment (Python 3.8+)`_, also known as
+  *bare-metal installation*.
 
-Once you have your *bare-metal* environment set-up (first option above),
-the next step is executing the ``fmriprep`` command-line.
-The ``fmriprep`` command-line options are documented in the :ref:`usage`
-section.
 The ``fmriprep`` command-line adheres to the `BIDS-Apps recommendations
 for the user interface <usage.html#execution-and-the-bids-format>`__.
-Therefore, the command-line has the following structure:
-::
+Therefore, the command-line has the following structure::
 
   $ fmriprep <input_bids_path> <derivatives_path> <analysis_level> <named_options>
 
-On the other hand, if you chose a container infrastructure, then
+The ``fmriprep`` command-line options are documented in the :ref:`usage`
+section.
+
+The command as shown works for a *bare-metal* environment set-up (second option above).
+If you choose the recommended container-based installation, then
 the command-line will be composed of a preamble to configure the
 container execution followed by the ``fmriprep`` command-line options
 as if you were running it on a *bare-metal* installation.
-The command-line structure above is then modified as follows:
-::
+The command-line structure above is then modified as follows::
 
   $ <container_command_and_options> <container_image> \
        <input_bids_path> <derivatives_path> <analysis_level> <fmriprep_named_options>
@@ -44,12 +42,12 @@ or `Singularity <https://www.nipreps.org/apps/singularity/>`__ subsections.
 The *NiPreps* portal also containes
 `extended details of execution with the Docker wrapper <https://www.nipreps.org/apps/docker/#running-a-niprep-with-a-lightweight-wrapper>`__.
 
-Manually Prepared Environment (Python 3.7+)
+Manually Prepared Environment (Python 3.8+)
 ===========================================
 
 .. warning::
 
-   This method is not recommended! Please checkout container alternatives.
+   This method is not recommended! Please consider using containers.
 
 Make sure all of *fMRIPrep*'s `External Dependencies`_ are installed.
 These tools must be installed and their binaries available in the
@@ -58,7 +56,7 @@ A relatively interpretable description of how your environment can be set-up
 is found in the `Dockerfile <https://github.com/nipreps/fmriprep/blob/master/Dockerfile>`_.
 As an additional installation setting, FreeSurfer requires a license file (see :ref:`fs_license`).
 
-On a functional Python 3.7 (or above) environment with ``pip`` installed,
+On a functional Python 3.8 (or above) environment with ``pip`` installed,
 *fMRIPrep* can be installed using the habitual command ::
 
     $ python -m pip install fmriprep
@@ -70,18 +68,18 @@ Check your installation with the ``--version`` argument ::
 
 External Dependencies
 ---------------------
-*fMRIPrep* is written using Python 3.7 (or above), and is based on
+*fMRIPrep* is written using Python 3.8 (or above), and is based on
 nipype_.
 
 *fMRIPrep* requires some other neuroimaging software tools that are
 not handled by the Python's packaging system (Pypi) used to deploy
 the ``fmriprep`` package:
 
-- FSL_ (version 6.0.6.2)
+- FSL_ (version 6.0.5.1)
 - ANTs_ (version 2.3.3 - NeuroDocker build)
-- AFNI_ (version Debian-23.0.00)
+- AFNI_ (version 22.3.06)
 - `C3D <https://sourceforge.net/projects/c3d/>`_ (version 1.3.0)
-- FreeSurfer_ (version 7.2.3)
+- FreeSurfer_ (version 7.3.2)
 - `ICA-AROMA <https://github.com/maartenmennes/ICA-AROMA/archive/v0.4.5.tar.gz>`_ (version 0.4.5)
 - `bids-validator <https://github.com/bids-standard/bids-validator>`_ (version 1.8.0)
 - `connectome-workbench <https://www.humanconnectome.org/software/connectome-workbench>`_ (version 1.5.0)

diff --git a/docs/outputs.rst b/docs/outputs.rst
@@ -33,8 +33,8 @@ upcoming `BEP 011`_ and `BEP 012`_).
        There are two exceptions to this principle (described in their corresponding
        sections below):
 
-         - ICA-AROMA's *non-aggressive* denoised outputs, and
-         - CompCor regressors, which are calculated after temporal high-pass filtering.
+       - ICA-AROMA's *non-aggressive* denoised outputs, and
+       - CompCor regressors, which are calculated after temporal high-pass filtering.
 
 Layout
 ------
@@ -61,7 +61,7 @@ records metadata recommended by the BIDS standard.
 This layout, now the default, may be explicitly specified with the
 ``--output-layout bids`` command-line option.
 For compatibility with versions of fMRIPrep prior to 21.0, the
-`legacy layout`_ is available via ``-output-layout legacy``.
+`legacy layout`_ is available via ``--output-layout legacy``.
 
 Visual Reports
 --------------
@@ -279,9 +279,9 @@ to perform more advanced denoising or alternative combination strategies.
    For example, when specifying a first-level model, you should set parameters in your
    software package or first-level model function accordingly (e.g., select the middle
    slice as reference).
-   Alternatively, you could manually adjust the volume onsets (e.g. as mentioned in 
+   Alternatively, you could manually adjust the volume onsets (e.g. as mentioned in
    the example above from [0, 2, 4] to [1, 3, 5]) or the event onsets accordingly.
-   
+
    Further information on this issue is found at
    `this blog post (with thanks to Russell Poldrack and Jeanette Mumford)
    <https://reproducibility.stanford.edu/slice-timing-correction-in-fmriprep-and-linear-modeling/>`__.
@@ -562,10 +562,10 @@ An example of these plots follows:
     and framewise-displacement ('FD').
     At the bottom, a 'carpetplot' summarizing the BOLD series [Power2016]_.
     The carpet plot rows correspond to voxelwise time series,
-    and are separated into regions: cortical gray matter, deep 
-    gray matter, white matter and cerebrospinal fluid, cerebellum 
+    and are separated into regions: cortical gray matter, deep
+    gray matter, white matter and cerebrospinal fluid, cerebellum
     and the brain-edge or “crown” [Provins2022]_.
-    The crown corresponds to the voxels located on a 
+    The crown corresponds to the voxels located on a
     closed band around the brain [Patriat2015]_.
 
 Noise components computed during each CompCor decomposition are evaluated according
@@ -676,8 +676,8 @@ the following invocation::
      and sensitivity of motion correction strategies for resting-state functional MRI. NeuroImage. 2018.
      doi:`10.1016/j.neuroimage.2017.12.073 <https://doi.org/10.1016/j.neuroimage.2017.12.073>`_
 
-  .. [Patriat2015] Patriat R, EK Molloy, RM Birn, T. Guitchev, and A. Popov. ,Using Edge Voxel Information to 
-     Improve Motion Regression for Rs-FMRI Connectivity Studies. Brain Connectivity. 2015. 
+  .. [Patriat2015] Patriat R, EK Molloy, RM Birn, T. Guitchev, and A. Popov. ,Using Edge Voxel Information to
+     Improve Motion Regression for Rs-FMRI Connectivity Studies. Brain Connectivity. 2015.
      doi:`10.1089/brain.2014.0321 <https://doi.org/10.1089/brain.2014.0321>`_.
 
   .. [Patriat2017] Patriat R, Reynolds RC, Birn RM, An improved model of motion-related signal

diff --git a/docs/spaces.rst b/docs/spaces.rst
@@ -80,10 +80,10 @@ Space modifiers such as ``res`` are combinatorial:
 ``--output-spaces MNIPediatricAsym:cohort-1:cohort-2:res-native:res-1`` will
 generate conversions for the following combinations:
 
-  * cohort ``1`` and "native" resolution (meaning, the original BOLD resolution),
-  * cohort ``1`` and resolution ``1`` of the template,
-  * cohort ``2`` and "native" resolution (meaning, the original BOLD resolution), and
-  * cohort ``2`` and resolution ``1`` of the template.
+* cohort ``1`` and "native" resolution (meaning, the original BOLD resolution),
+* cohort ``1`` and resolution ``1`` of the template,
+* cohort ``2`` and "native" resolution (meaning, the original BOLD resolution), and
+* cohort ``2`` and resolution ``1`` of the template.
 
 Please mind that the selected resolutions specified must exist within TemplateFlow.
 
@@ -120,19 +120,19 @@ Nonstandard spaces
 Additionally, ``--output-spaces`` accepts identifiers of spatial references
 that do not generate *standardized* coordinate spaces:
 
-  * ``T1w`` or ``anat``: data are resampled into the individual's anatomical
-    reference generated with the T1w and T2w images available within the
-    BIDS structure.
-  * ``fsnative``: similarly to the ``anat`` space for volumetric references,
-    including the ``fsnative`` space will instruct *fMRIPrep* to sample the
-    original BOLD data onto FreeSurfer's reconstructed surfaces for this
-    individual.
-  * ``func``, ``bold``, ``run``, ``boldref`` or ``sbref`` can be used to
-    generate BOLD data in their original grid, after slice-timing,
-    head-motion, and susceptibility-distortion corrections.
-    These keywords are experimental, and expected to change because
-    **additional nonstandard spaces** are currently being discussed
-    `here <https://github.com/nipreps/fmriprep/issues/1604>`__.
+* ``T1w`` or ``anat``: data are resampled into the individual's anatomical
+  reference generated with the T1w and T2w images available within the
+  BIDS structure.
+* ``fsnative``: similarly to the ``anat`` space for volumetric references,
+  including the ``fsnative`` space will instruct *fMRIPrep* to sample the
+  original BOLD data onto FreeSurfer's reconstructed surfaces for this
+  individual.
+* ``func``, ``bold``, ``run``, ``boldref`` or ``sbref`` can be used to
+  generate BOLD data in their original grid, after slice-timing,
+  head-motion, and susceptibility-distortion corrections.
+  These keywords are experimental, and expected to change because
+  **additional nonstandard spaces** are currently being discussed
+  `here <https://github.com/nipreps/fmriprep/issues/1604>`__.
 
 Modifiers are not allowed when providing nonstandard spaces.
 

diff --git a/docs/usage.rst b/docs/usage.rst
@@ -43,7 +43,7 @@ The command-line interface of the docker wrapper
 ------------------------------------------------
 
 .. argparse::
-   :ref: fmriprep_docker.get_parser
+   :ref: fmriprep_docker.__main__.get_parser
    :prog: fmriprep-docker
    :nodefault:
    :nodefaultconst:
@@ -212,4 +212,4 @@ following mailing list: http://mail.python.org/mailman/listinfo/neuroimaging
 Please add *[fmriprep]* to the subject line when posting on the mailing list.
 
 
-.. include:: license.rst
+.. include:: license.rst