ENH: Add flag for STC reference time and set in all cases

fmriprep/cli/parser.py

@@ -81,6 +81,21 @@ def _bids_filter(value):
         if value and Path(value).exists():
             return loads(Path(value).read_text(), object_hook=_filter_pybids_none_any)
 
+    def _slice_time_ref(value, parser):
+        if value == "start":
+            value = 0
+        elif value == "middle":
+            value = 1
+        try:
+            value = float(value)
+        except ValueError:
+            raise parser.error("Slice time reference must be number, 'start', or 'middle'. "
+                               f"Received {value}.")
+        if not 0 <= val <= 1:
+            raise parser.error(f"Slice time reference must be in range 0-1. Received {value}.")
+        return value
+
+
     verstr = f"fMRIPrep v{config.environment.version}"
     currentv = Version(config.environment.version)
     is_release = not any(
@@ -329,6 +344,17 @@ def _bids_filter(value):
         help="Replace medial wall values with NaNs on functional GIFTI files. Only "
         "performed for GIFTI files mapped to a freesurfer subject (fsaverage or fsnative).",
     )
+    g_conf.add_argument(
+        "--slice-time-ref",
+        required=False,
+        action="store",
+        default=None,
+        type=_slice_time_ref,
+        help="The time of the reference slice to correct BOLD values to, as a fraction "
+             "acquisition time. 0 indicates the start, 0.5 the midpoint, and 1 the end "
+             "of acquisition. The alias `start` corresponds to 0, and `middle` to 0.5. "
+             "The default value is 0.5.",
+    )
     g_conf.add_argument(
         "--dummy-scans",
         required=False,

fmriprep/config.py

@@ -550,6 +550,11 @@ class workflow(_Config):
     skull_strip_t1w = "force"
     """Skip brain extraction of the T1w image (default is ``force``, meaning that
     *fMRIPrep* will run brain extraction of the T1w)."""
+    slice_time_ref = 0.5
+    """The time of the reference slice to correct BOLD values to, as a fraction
+    acquisition time. 0 indicates the start, 0.5 the midpoint, and 1 the end
+    of acquisition. The alias `start` corresponds to 0, and `middle` to 0.5.
+    The default value is 0.5."""
     spaces = None
     """Keeps the :py:class:`~niworkflows.utils.spaces.SpatialReferences`
     instance keeping standard and nonstandard spaces."""

fmriprep/workflows/bold/stc.py

@@ -93,22 +93,29 @@ def init_bold_stc_wf(metadata, name='bold_stc_wf'):
     from niworkflows.engine.workflows import LiterateWorkflow as Workflow
     from niworkflows.interfaces.header import CopyXForm
 
+    slice_times = metadata["SliceTiming"]
+    first, last = min(slice_times), max(slice_times)
+    frac = config.workflow.slice_time_ref
+    tzero = first + frac * (last - first)
+
+    afni_ver = ''.join('%02d' % v for v in afni.Info().version() or [])
     workflow = Workflow(name=name)
-    workflow.__desc__ = """\
-BOLD runs were slice-time corrected using `3dTshift` from
-AFNI {afni_ver} [@afni, RRID:SCR_005927].
-""".format(afni_ver=''.join(['%02d' % v for v in afni.Info().version() or []]))
+    workflow.__desc__ = f"""\
+BOLD runs were slice-time corrected to {tzero:0.3g}s ({frac:g} of slice acquisition range
+{first:.3g}s-{last:.3g}s) using `3dTshift` from AFNI {afni_ver} [@afni, RRID:SCR_005927].
+"""
     inputnode = pe.Node(niu.IdentityInterface(fields=['bold_file', 'skip_vols']), name='inputnode')
     outputnode = pe.Node(niu.IdentityInterface(fields=['stc_file']), name='outputnode')
 
-    LOGGER.log(25, 'Slice-timing correction will be included.')
+    LOGGER.log(25, f'BOLD series will be slice-timing corrected to an offset of {tzero:.3g}.')
 
     # It would be good to fingerprint memory use of afni.TShift
     slice_timing_correction = pe.Node(
         TShift(outputtype='NIFTI_GZ',
                tr=f"{metadata['RepetitionTime']}s",
                slice_timing=metadata['SliceTiming'],
-               slice_encoding_direction=metadata.get('SliceEncodingDirection', 'k')),
+               slice_encoding_direction=metadata.get('SliceEncodingDirection', 'k'),
+               tzero=tzero),
         name='slice_timing_correction')
 
     copy_xform = pe.Node(CopyXForm(), name='copy_xform', mem_gb=0.1)