feat: Add --force flag, deprecate --force[-no]-bbr

Author: effigies

fmriprep/cli/parser.py

@@ -48,6 +48,8 @@ def _build_parser(**kwargs):
         'aroma_err_on_warn': (None, '24.0.0'),
         'bold2t1w_init': ('--bold2anat-init', '24.2.0'),
         'bold2t1w_dof': ('--bold2anat-dof', '24.2.0'),
+        'force_bbr': ('--force bbr', '26.0.0'),
+        'force_no_bbr': ('--force no-bbr', '26.0.0'),
     }
 
     class DeprecatedAction(Action):
@@ -338,6 +340,16 @@ def _slice_time_ref(value, parser):
         help='Ignore selected aspects of the input dataset to disable corresponding '
         'parts of the workflow (a space delimited list)',
     )
+    g_conf.add_argument(
+        '--force',
+        required=False,
+        action='store',
+        nargs='+',
+        default=[],
+        choices=['bbr', 'no-bbr'],
+        help='Force selected processing choices, overriding automatic selections '
+        '(a space delimited list)',
+    )
     g_conf.add_argument(
         '--output-spaces',
         nargs='*',
@@ -392,17 +404,13 @@ def _slice_time_ref(value, parser):
     )
     g_conf.add_argument(
         '--force-bbr',
-        action='store_true',
-        dest='use_bbr',
-        default=None,
-        help='Always use boundary-based registration (no goodness-of-fit checks)',
+        action=DeprecatedAction,
+        help='Deprecated - use `--force bbr` instead.',
     )
     g_conf.add_argument(
         '--force-no-bbr',
-        action='store_false',
-        dest='use_bbr',
-        default=None,
-        help='Do not use boundary-based registration (no goodness-of-fit checks)',
+        action=DeprecatedAction,
+        help='Deprecated - use `--force no-bbr` instead.',
     )
     g_conf.add_argument(
         '--slice-time-ref',

fmriprep/config.py

@@ -581,6 +581,8 @@ class workflow(_Config):
     """Adjust pipeline to reuse base template of existing longitudinal freesurfer"""
     ignore = None
     """Ignore particular steps for *fMRIPrep*."""
+    force = None
+    """Force particular steps for *fMRIPrep*."""
     level = None
     """Level of preprocessing to complete. One of ['minimal', 'resampling', 'full']."""
     longitudinal = False

fmriprep/workflows/bold/fit.py

@@ -613,11 +613,18 @@ def init_bold_fit_wf(
         ])  # fmt:skip
 
     if not boldref2anat_xform:
+        use_bbr = (
+            True
+            if 'bbr' in config.workflow.force
+            else False
+            if 'no-bbr' in config.workflow.force
+            else None
+        )
         # calculate BOLD registration to T1w
         bold_reg_wf = init_bold_reg_wf(
             bold2anat_dof=config.workflow.bold2anat_dof,
             bold2anat_init=config.workflow.bold2anat_init,
-            use_bbr=config.workflow.use_bbr,
+            use_bbr=use_bbr,
             freesurfer=config.workflow.run_reconall,
             omp_nthreads=omp_nthreads,
             mem_gb=mem_gb['resampled'],

fmriprep/workflows/tests/test_base.py

@@ -106,7 +106,6 @@ def bids_root(tmp_path_factory):
 
 def _make_params(
     bold2anat_init: str = 'auto',
-    use_bbr: bool | None = None,
     dummy_scans: int | None = None,
     me_output_echos: bool = False,
     medial_surface_nan: bool = False,
@@ -118,15 +117,17 @@ def _make_params(
     force_syn: bool = False,
     freesurfer: bool = True,
     ignore: list[str] = None,
+    force: list[str] = None,
     bids_filters: dict = None,
 ):
     if ignore is None:
         ignore = []
+    if force is None:
+        force = []
     if bids_filters is None:
         bids_filters = {}
     return (
         bold2anat_init,
-        use_bbr,
         dummy_scans,
         me_output_echos,
         medial_surface_nan,
@@ -138,6 +139,7 @@ def _make_params(
         force_syn,
         freesurfer,
         ignore,
+        force,
         bids_filters,
     )
 
@@ -147,7 +149,6 @@ def _make_params(
 @pytest.mark.parametrize(
     (
         'bold2anat_init',
-        'use_bbr',
         'dummy_scans',
         'me_output_echos',
         'medial_surface_nan',
@@ -159,18 +160,19 @@ def _make_params(
         'force_syn',
         'freesurfer',
         'ignore',
+        'force',
         'bids_filters',
     ),
     [
         _make_params(),
         _make_params(bold2anat_init='t1w'),
         _make_params(bold2anat_init='t2w'),
         _make_params(bold2anat_init='header'),
-        _make_params(use_bbr=True),
-        _make_params(use_bbr=False),
-        _make_params(bold2anat_init='header', use_bbr=True),
+        _make_params(force=['bbr']),
+        _make_params(force=['no-bbr']),
+        _make_params(bold2anat_init='header', force=['bbr']),
         # Currently disabled
-        # _make_params(bold2anat_init="header", use_bbr=False),
+        # _make_params(bold2anat_init="header", force=['no-bbr']),
         _make_params(dummy_scans=2),
         _make_params(me_output_echos=True),
         _make_params(medial_surface_nan=True),
@@ -182,12 +184,12 @@ def _make_params(
         _make_params(skull_strip_t1w='skip'),
         _make_params(use_syn_sdc='warn', force_syn=True, ignore=['fieldmaps']),
         _make_params(freesurfer=False),
-        _make_params(freesurfer=False, use_bbr=True),
-        _make_params(freesurfer=False, use_bbr=False),
+        _make_params(freesurfer=False, force=['bbr']),
+        _make_params(freesurfer=False, force=['no-bbr']),
         # Currently unsupported:
         # _make_params(freesurfer=False, bold2anat_init="header"),
-        # _make_params(freesurfer=False, bold2anat_init="header", use_bbr=True),
-        # _make_params(freesurfer=False, bold2anat_init="header", use_bbr=False),
+        # _make_params(freesurfer=False, bold2anat_init="header", force=['bbr']),
+        # _make_params(freesurfer=False, bold2anat_init="header", force=['no-bbr']),
         # Regression test for gh-3154:
         _make_params(bids_filters={'sbref': {'suffix': 'sbref'}}),
     ],
@@ -198,7 +200,6 @@ def test_init_fmriprep_wf(
     level: str,
     anat_only: bool,
     bold2anat_init: str,
-    use_bbr: bool | None,
     dummy_scans: int | None,
     me_output_echos: bool,
     medial_surface_nan: bool,
@@ -210,13 +211,13 @@ def test_init_fmriprep_wf(
     force_syn: bool,
     freesurfer: bool,
     ignore: list[str],
+    force: list[str],
     bids_filters: dict,
 ):
     with mock_config(bids_dir=bids_root):
         config.workflow.level = level
         config.workflow.anat_only = anat_only
         config.workflow.bold2anat_init = bold2anat_init
-        config.workflow.use_bbr = use_bbr
         config.workflow.dummy_scans = dummy_scans
         config.execution.me_output_echos = me_output_echos
         config.workflow.medial_surface_nan = medial_surface_nan
@@ -226,6 +227,7 @@ def test_init_fmriprep_wf(
         config.workflow.cifti_output = cifti_output
         config.workflow.run_reconall = freesurfer
         config.workflow.ignore = ignore
+        config.workflow.force = force
         with patch.dict('fmriprep.config.execution.bids_filters', bids_filters):
             wf = init_fmriprep_wf()