diff --git a/docs/usage.rst b/docs/usage.rst index fc2481ab0..905e63531 100644 --- a/docs/usage.rst +++ b/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 ``) -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 `__, 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 `__, - 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 `__ 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.