Merge pull request #2039 from oesteban/enh/skip-anat-brain-extraction

ENH: Add a ``--skull-strip-t1w`` argument to skip brain extraction

docs/workflows.rst

@@ -55,6 +55,22 @@ single reference template (see `Longitudinal processing`_).
         t1w=['sub-01/anat/sub-01_T1w.nii.gz'],
     )
 
+.. important::
+
+    Occasionally, openly shared datasets may contain preprocessed anatomical images
+    as if they are unprocessed.
+    In the case of brain-extracted (skull-stripped) T1w images, attempting to perform
+    brain extraction again will often have poor results and may cause *fMRIPrep* to crash.
+    By default, *fMRIPrep* will attempt to detect these cases using a heuristic to check if the
+    T1w image is already masked.
+    If this heuristic fails, and you know your images are skull-stripped, you can skip brain
+    extraction with ``--skull-strip-t1w skip``.
+    Likewise, if you know your images are not skull-stripped and the heuristic incorrectly
+    determines that they are, you can force skull stripping with ``--skull-strip-t1w force``.
+    The default behavior of detecting pre-extracted brains may be explicitly requested with
+    ``---skull-strip-t1w auto``, which will use a heuristic to check if each image is
+    already masked.
+
 See also *sMRIPrep*'s
 :py:func:`~smriprep.workflows.anatomical.init_anat_preproc_wf`.
 

fmriprep/cli/parser.py

@@ -211,6 +211,11 @@ def _bids_filter(value):
     g_ants.add_argument('--skull-strip-fixed-seed', action='store_true',
                         help='do not use a random seed for skull-stripping - will ensure '
                              'run-to-run replicability when used with --omp-nthreads 1')
+    g_ants.add_argument(
+        '--skull-strip-t1w', action='store', choices=('auto', 'skip', 'force'), default='force',
+        help="determiner for T1-weighted skull stripping ('force' ensures skull "
+             "stripping, 'skip' ignores skull stripping, and 'auto' applies brain extraction "
+             "based on the outcome of a heuristic to check whether the brain is already masked).")
 
     # Fieldmap options
     g_fmap = parser.add_argument_group('Specific options for handling fieldmaps')
@@ -349,6 +354,19 @@ def parse_args(args=None, namespace=None):
             'Per-process threads (--omp-nthreads=%d) exceed total '
             'threads (--nthreads/--n_cpus=%d)', config.nipype.omp_nthread, config.nipype.nprocs)
 
+    # Inform the user about the risk of using brain-extracted images
+    if config.workflow.skull_strip_t1w == "auto":
+        build_log.warning("""\
+Option ``--skull-strip-t1w`` was set to 'auto'. A heuristic will be \
+applied to determine whether the input T1w image(s) have already been skull-stripped.
+If that were the case, brain extraction and INU correction will be skipped for those T1w \
+inputs. Please, BEWARE OF THE RISKS TO THE CONSISTENCY of results when using varying \
+processing workflows across participants. To determine whether a participant has been run \
+through the shortcut pipeline (meaning, brain extraction was skipped), please check the \
+citation boilerplate. When reporting results with varying pipelines, please make sure you \
+mention this particular variant of fMRIPrep listing the participants for which it was \
+applied.""")
+
     bids_dir = config.execution.bids_dir
     output_dir = config.execution.output_dir
     work_dir = config.execution.work_dir

fmriprep/config.py

@@ -439,6 +439,9 @@ class workflow(_Config):
     """Fix a seed for skull-stripping."""
     skull_strip_template = "OASIS30ANTs"
     """Change default brain extraction template."""
+    skull_strip_t1w = "force"
+    """Skip brain extraction of the T1w image (default is ``force``, meaning that
+    *fMRIPrep* will run brain extraction of the T1w)."""
     spaces = None
     """Keeps the :py:class:`~niworkflows.utils.spaces.SpatialReferences`
     instance keeping standard and nonstandard spaces."""

fmriprep/workflows/base.py

@@ -226,7 +226,7 @@ def init_single_subject_wf(subject_id):
         output_dir=str(config.execution.output_dir),
         reportlets_dir=reportlets_dir,
         skull_strip_fixed_seed=config.workflow.skull_strip_fixed_seed,
-        skull_strip_mode='force',
+        skull_strip_mode=config.workflow.skull_strip_t1w,
         skull_strip_template=Reference.from_string(
             config.workflow.skull_strip_template)[0],
         spaces=spaces,