feat: Ignore non-steady-state volumes in T2*/S0 estimation (#3556)

Closes #3507. As of 25.1.0, tedana has an `--exclude` parameter in its
t2smap CLI, which allows users to ignore certain volumes when estimating
T2* and S0. This PR bumps the tedana version and leverages that
parameter to ignore dummy scans. If it proves useful, we could also
ignore high-motion volumes in the future.

## Changes proposed in this pull request

- Increase minimum tedana version from 25.0.0 to 25.1.0.
- Use estimated number of dummy scans to set `exclude` parameter in
t2smap call, so that those volumes do not contribute to the estimation
of T2*, which is in turn used to optimally combine the data across
echoes. I doubt the dummy scans actually have much effect on T2*
estimation, but it still stands to reason that they are not _helping_.

## Documentation that should be reviewed
<!--
Please summarize here the main changes to the documentation that the
reviewers should be aware of.
-->



<!--
Welcome, new contributors!

We ask you to read through the Contributing Guide:
https://github.com/nipreps/fmriprep/blob/master/CONTRIBUTING.md

These are guidelines intended to make communication easier by describing
a consistent process, but
don't worry if you don't get it everything exactly "right" on the first
try.

To boil it down, here are some highlights:

1) Consider starting a conversation in the issues list before submitting
a pull request. The discussion might save you a
   lot of time coding.
2) Please use descriptive prefixes in your pull request title, such as
"ENH:" for an enhancement or "FIX:" for a bug fix.
(See the Contributing guide for the full set.) And consider adding a
"WIP" tag for works-in-progress.
3) Any code you submit will be licensed under the same terms (Apache
License 2.0) as the rest of fMRIPrep.
4) We invite every contributor to add themselves to the `.zenodo.json`
file
(https://github.com/nipreps/fmriprep/blob/master/.zenodo.json), which
will result in your being listed as an author
at the next release. Please add yourself as the next-to-last entry, just
above Russ.

A pull request is a conversation. We may ask you to make some changes
before accepting your PR,
and likewise, you should feel free to ask us any questions you have.

-->

Author: effigies

fmriprep/interfaces/multiecho.py

@@ -68,6 +68,11 @@ class T2SMapInputSpec(CommandLineInputSpec):
             'monoexponential model is fit to the raw data.'
         ),
     )
+    n_exclude = traits.Int(
+        argstr='--exclude 0:%d',
+        position=5,
+        desc='Number of volumes from the beginning of the run to exclude from T2*/S0 estimation.',
+    )
 
 
 class T2SMapOutputSpec(TraitedSpec):

fmriprep/workflows/bold/fit.py

@@ -981,7 +981,10 @@ def init_bold_native_wf(
         # Do NOT set motion_xfm on outputnode
         # This prevents downstream resamplers from double-dipping
         workflow.connect([
-            (inputnode, bold_t2s_wf, [('bold_mask', 'inputnode.bold_mask')]),
+            (inputnode, bold_t2s_wf, [
+                ('bold_mask', 'inputnode.bold_mask'),
+                ('dummy_scans', 'inputnode.skip_vols'),
+            ]),
             (boldref_bold, join_echos, [('out_file', 'bold_files')]),
             (join_echos, bold_t2s_wf, [('bold_files', 'inputnode.bold_file')]),
             (join_echos, outputnode, [('bold_files', 'bold_echos')]),

fmriprep/workflows/bold/t2s.py

@@ -107,7 +107,10 @@ def init_bold_t2s_wf(
 The optimally combined time series was carried forward as the *preprocessed BOLD*.
 """
 
-    inputnode = pe.Node(niu.IdentityInterface(fields=['bold_file', 'bold_mask']), name='inputnode')
+    inputnode = pe.Node(
+        niu.IdentityInterface(fields=['bold_file', 'bold_mask', 'skip_vols']),
+        name='inputnode',
+    )
 
     outputnode = pe.Node(niu.IdentityInterface(fields=['bold', 't2star_map']), name='outputnode')
 
@@ -122,7 +125,10 @@ def init_bold_t2s_wf(
     )
     workflow.connect([
         (inputnode, dilate_mask, [('bold_mask', 'in_mask')]),
-        (inputnode, t2smap_node, [('bold_file', 'in_files')]),
+        (inputnode, t2smap_node, [
+            ('bold_file', 'in_files'),
+            ('skip_vols', 'n_exclude'),
+        ]),
         (dilate_mask, t2smap_node, [('out_mask', 'mask_file')]),
         (t2smap_node, outputnode, [('optimal_comb', 'bold'),
                                    ('t2star_map', 't2star_map')]),

pixi.lock

@@ -36,7 +36,7 @@ dependencies = [
     "requests >= 2.27",
     "sdcflows >= 2.15.0",
     "smriprep >= 0.19.2",
-    "tedana >= 25.0.0",
+    "tedana >= 25.1.0",
     "templateflow >= 24.2.2",
     "transforms3d >= 0.4.2",
     "toml >= 0.10",