feat: Add flag to set TRT fallback behavior

Author: effigies

fmriprep/cli/parser.py

@@ -149,6 +149,16 @@ def _slice_time_ref(value, parser):
             raise parser.error(f'Slice time reference must be in range 0-1. Received {value}.')
         return value
 
+    def _fallback_trt(value, parser):
+        if value == 'estimated':
+            return value
+        try:
+            return float(value)
+        except ValueError:
+            raise parser.error(
+                f'Falling back to TRT must be a number or "estimated". Received {value}.'
+            ) from None
+
     verstr = f'fMRIPrep v{config.environment.version}'
     currentv = Version(config.environment.version)
     is_release = not any((currentv.is_devrelease, currentv.is_prerelease, currentv.is_postrelease))
@@ -163,6 +173,7 @@ def _slice_time_ref(value, parser):
     PositiveInt = partial(_min_one, parser=parser)
     BIDSFilter = partial(_bids_filter, parser=parser)
     SliceTimeRef = partial(_slice_time_ref, parser=parser)
+    FallbackTRT = partial(_fallback_trt, parser=parser)
 
     # Arguments as specified by BIDS-Apps
     # required, positional arguments
@@ -417,6 +428,15 @@ def _slice_time_ref(value, parser):
         type=int,
         help='Number of nonsteady-state volumes. Overrides automatic detection.',
     )
+    g_conf.add_argument(
+        '--fallback-total-readout-time',
+        required=False,
+        action='store',
+        default=None,
+        type=FallbackTRT,
+        help='Fallback value for Total Readout Time (TRT) calculation. '
+        'May be a number or "estimated".',
+    )
     g_conf.add_argument(
         '--random-seed',
         dest='_random_seed',

fmriprep/config.py

@@ -575,6 +575,9 @@ class workflow(_Config):
     """Remove the mean from fieldmaps."""
     force_syn = None
     """Run *fieldmap-less* susceptibility-derived distortions estimation."""
+    fallback_total_readout_time = None
+    """Infer the total readout time if unavailable from authoritative metadata.
+    This may be a number or the string "estimated"."""
     hires = None
     """Run FreeSurfer ``recon-all`` with the ``-hires`` flag."""
     fs_no_resume = None

fmriprep/interfaces/resampling.py

@@ -191,6 +191,13 @@ def _run_interface(self, runtime):
 class DistortionParametersInputSpec(TraitedSpec):
     in_file = File(exists=True, desc='EPI image corresponding to the metadata')
     metadata = traits.Dict(mandatory=True, desc='metadata corresponding to the inputs')
+    fallback = traits.Either(
+        None,
+        'estimated',
+        traits.Float,
+        usedefault=True,
+        desc='Fallback value for missing metadata',
+    )
 
 
 class DistortionParametersOutputSpec(TraitedSpec):
@@ -215,6 +222,8 @@ def _run_interface(self, runtime):
             self._results['readout_time'] = get_trt(
                 self.inputs.metadata,
                 self.inputs.in_file or None,
+                use_estimate=self.inputs.fallback == 'estimated',
+                fallback=self.inputs.fallback if isinstance(self.inputs.fallback, float) else None,
             )
             self._results['pe_direction'] = self.inputs.metadata['PhaseEncodingDirection']
         except (KeyError, ValueError):

fmriprep/workflows/bold/apply.py

@@ -17,6 +17,7 @@ def init_bold_volumetric_resample_wf(
     metadata: dict,
     mem_gb: dict[str, float],
     jacobian: bool,
+    fallback_total_readout_time: str | float | None = None,
     fieldmap_id: str | None = None,
     omp_nthreads: int = 1,
     name: str = 'bold_volumetric_resample_wf',
@@ -161,7 +162,10 @@ def init_bold_volumetric_resample_wf(
         run_without_submitting=True,
     )
     distortion_params = pe.Node(
-        DistortionParameters(metadata=metadata),
+        DistortionParameters(
+            metadata=metadata,
+            fallback=fallback_total_readout_time,
+        ),
         name='distortion_params',
         run_without_submitting=True,
     )

fmriprep/workflows/bold/base.py

@@ -383,6 +383,7 @@ def init_bold_wf(
     # Resample to anatomical space
     bold_anat_wf = init_bold_volumetric_resample_wf(
         metadata=all_metadata[0],
+        fallback_total_readout_time=config.workflow.fallback_total_readout_time,
         fieldmap_id=fieldmap_id if not multiecho else None,
         omp_nthreads=omp_nthreads,
         mem_gb=mem_gb,

fmriprep/workflows/bold/fit.py

@@ -859,7 +859,11 @@ def init_bold_native_wf(
         )
 
         distortion_params = pe.Node(
-            DistortionParameters(metadata=metadata, in_file=bold_file),
+            DistortionParameters(
+                metadata=metadata,
+                in_file=bold_file,
+                fallback=config.workflow.fallback_total_readout_time,
+            ),
             name='distortion_params',
             run_without_submitting=True,
         )