DOC: Update usage.rst with notes on reusing derivatives

Author: effigies

docs/usage.rst

@@ -128,10 +128,13 @@ would be equivalent to the latest example: ::
 
 Reusing precomputed derivatives
 -------------------------------
+
 Reusing a previous, partial execution of *fMRIPrep*
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 *fMRIPrep* will pick up where it left off a previous execution, so long as the work directory
 points to the same location, and this directory has not been changed/manipulated.
+Some workflow nodes will rerun unconditionally, so there will always be some amount of
+reprocessing.
 
 Using a previous run of *FreeSurfer*
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -143,48 +146,39 @@ You can use the ``--fs-subjects-dir`` flag to specify a different location to sa
 FreeSurfer outputs.
 If precomputed results are found, they will be reused.
 
-The *anatomical fast-track*
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Starting with version 20.1.0, *fMRIPrep* has a command-line argument (``--anat-derivatives <PATH>``)
-to indicate a path from which the preprocessed information derived from the T1w, T2w (if present) and
-FLAIR (if present) images.
-This feature was envisioned to help process very large multi-session datasets where the anatomical
-images can be averaged (i.e., anatomy is not expected to vary substantially across sessions).
-An example where this kind of processing would be useful is
-`My Connectome <https://openneuro.org/datasets/ds000031/>`__, a dataset that contains
-107 sessions for a single-subject.
-Most of these sessions contain anatomical information which, given the design of the dataset, can be averaged
-across sessions as no substantial changes should happen.
-In other words, the anatomical information of the dataset can be considered as *cross-sectional*.
-Before version 20.1.0, preprocessing this dataset would be hard for two limitations:
-
-  * if the dataset were to be processed in just one enormous job (be it in a commercial Cloud or
-    :abbr:`HPC (high-performance computing)` resources), the amount of data to be processed surely
-    would exceed the time limitations per job (and/or related issues, such as restarting from where
-    it left before); or
-  * if the processing were `split in sessions <https://github.com/nipreps/fmriprep/issues/1175>`__,
-    then *fMRIPrep* would attempt to re-process the anatomical information for every session.
-
-Because processing this emerging type of datasets (*densely sampled neuroimaging*) was impractical with
-*fMRIPrep*, the option ``--anat-derivatives`` will shortcut the whole anatomical processing.
-
-.. danger::
-    Using the *anatomical fast-track* (the ``--anat-derivatives`` argument) has important side-effects
-    that risk the reproducibility and reliability of *fMRIPrep*.
-    This flag breaks *fMRIPrep*'s internal tracing of provenance, and it trusts whatever input *fMRIPrep*
-    is given (so long it is BIDS-Derivatives compliant and contains all the necessary files).
-
-    When reporting results obtained with ``--anat-derivatives``, please make sure you highlight this
-    particular deviation from *fMRIPrep*, and clearly describe the alternative preprocessing of
-    anatomical data.
-
-.. attention::
-    When the intention is to combine the *anatomical fast-track* with some advanced options that involve
-    standard spaces (e.g., ``--cifti-output``), please make sure you include the
-    ``MNI152NLin6Asym`` space to the ``--output-spaces`` list in the first invocation of *fMRIPrep*
-    (or *sMRIPrep*) from which the results are to be reused.
-    Otherwise, a warning message indicating that *fMRIPrep*'s expectations were not met will be issued,
-    and the pre-computed anatomical derivatives will not be reused.
+BIDS Derivatives reuse
+~~~~~~~~~~~~~~~~~~~~~~
+As of version 23.2.0, *fMRIPrep* can reuse precomputed derivatives that follow BIDS Derivatives
+conventions. To provide derivatives to *fMRIPrep*, use the ``--derivatives`` (``-d``) flag one
+or more times.
+
+This mechanism replaces the earlier, more limited ``--anat-derivatives`` flag.
+
+.. note::
+   Derivatives reuse is considered *experimental*.
+
+This feature has several intended use-cases:
+
+  * To enable fMRIPrep to be run in a "minimal" mode, where only the most essential
+    derivatives are generated. This can be useful for large datasets where disk space
+    is a concern, or for users who only need a subset of the derivatives. Further
+    derivatives may be generated later, or by a different tool.
+  * To enable fMRIPrep to be integrated into a larger processing pipeline, where
+    other tools may generate derivatives that fMRIPrep can use in place of its own
+    steps.
+  * To enable users to substitute their own custom derivatives for those generated
+    by fMRIPrep. For example, a user may wish to use a different brain extraction
+    tool, or a different registration tool, and then use fMRIPrep to generate the
+    remaining derivatives.
+  * To enable complicated meta-workflows, where fMRIPrep is run multiple times
+    with different options, and the results are combined. For example, the
+    `My Connectome <https://openneuro.org/datasets/ds000031/>`__ dataset contains
+    107 sessions for a single-subject. Processing of all sessions simultaneously
+    would be impractical, but the anatomical processing can be done once, and
+    then the functional processing can be done separately for each session.
+
+See also the ``--level`` flag, which can be used to control which derivatives are
+generated.
 
 Troubleshooting
 ---------------
@@ -195,7 +189,7 @@ Information on how to customize and understand these files can be found on the
 page.
 
 **Support and communication**.
-The documentation of this project is found here: https://fmriprep.readthedocs.org/en/latest/.
+The documentation of this project is found here: https://fmriprep.org/en/latest/.
 
 All bugs, concerns and enhancement requests for this software can be submitted here:
 https://github.com/nipreps/fmriprep/issues.