Exclude echo entity from optimally combined derivatives (#3166)

Closes #3165. - Ensure that the echo entity is removed from CIFTI optimally combined derivatives. - Ensure that the echo entity is _retained_ in derivatives when `--echo-idx` is used to process multi-echo data like single-echo. - I initially ran the ds210 test with `--echo-idx 1` to determine if `echo` was being retained in the filenames. It wasn't, but the `dismiss_echo` function fixed that. - Add function, `fmriprep.utils.bids.dismiss_echo`, to include `echo` in `dismiss_entities` parameters only when applicable, based on the config.
nipreps · Dec 6, 2023 · d24f585 · d24f585
2 parents 3c836e8 + fa402de
commit d24f585
Show file tree

Hide file tree

Showing 6 changed files with 49 additions and 25 deletions.
diff --git a/fmriprep/utils/bids.py b/fmriprep/utils/bids.py
@@ -34,6 +34,7 @@
 from bids.utils import listify
 from packaging.version import Version
 
+from .. import config
 from ..data import load as load_data
 
 
@@ -324,3 +325,15 @@ def _unique(inlist):
         return inlist
 
     return {k: _unique(v) for k, v in entities.items()}
+
+
+def dismiss_echo(entities=None):
+    """Set entities to dismiss in a DerivativesDataSink."""
+    if entities is None:
+        entities = []
+
+    echo_idx = config.execution.echo_idx
+    if echo_idx is None or len(listify(echo_idx)) > 2:
+        entities.append("echo")
+
+    return entities
diff --git a/fmriprep/workflows/base.py b/fmriprep/workflows/base.py
@@ -43,6 +43,7 @@
 from .. import config
 from ..interfaces import DerivativesDataSink
 from ..interfaces.reports import AboutSummary, SubjectSummary
+from ..utils.bids import dismiss_echo
 
 
 def init_fmriprep_wf():
@@ -296,7 +297,7 @@ def init_single_subject_wf(subject_id: str):
             base_directory=config.execution.fmriprep_dir,
             desc='summary',
             datatype="figures",
-            dismiss_entities=("echo",),
+            dismiss_entities=dismiss_echo(),
         ),
         name='ds_report_summary',
         run_without_submitting=True,
@@ -307,7 +308,7 @@ def init_single_subject_wf(subject_id: str):
             base_directory=config.execution.fmriprep_dir,
             desc='about',
             datatype="figures",
-            dismiss_entities=("echo",),
+            dismiss_entities=dismiss_echo(),
         ),
         name='ds_report_about',
         run_without_submitting=True,

diff --git a/fmriprep/workflows/bold/base.py b/fmriprep/workflows/bold/base.py
@@ -39,6 +39,7 @@
 
 from ... import config
 from ...interfaces import DerivativesDataSink
+from ...utils.bids import dismiss_echo
 from ...utils.misc import estimate_bold_mem_usage
 
 # BOLD workflows
@@ -367,7 +368,7 @@ def init_bold_wf(
             DerivativesDataSink(
                 desc="t2scomp",
                 datatype="figures",
-                dismiss_entities=("echo",),
+                dismiss_entities=dismiss_echo(),
             ),
             name="ds_report_t2scomp",
             run_without_submitting=True,
@@ -377,7 +378,7 @@ def init_bold_wf(
             DerivativesDataSink(
                 desc="t2starhist",
                 datatype="figures",
-                dismiss_entities=("echo",),
+                dismiss_entities=dismiss_echo(),
             ),
             name="ds_report_t2star_hist",
             run_without_submitting=True,
@@ -532,6 +533,7 @@ def init_bold_wf(
         ds_bold_cifti = pe.Node(
             DerivativesDataSink(
                 base_directory=fmriprep_dir,
+                dismiss_entities=dismiss_echo(),
                 space='fsLR',
                 density=config.workflow.cifti_output,
                 suffix='bold',
@@ -603,7 +605,7 @@ def init_bold_wf(
             base_directory=fmriprep_dir,
             desc='confounds',
             suffix='timeseries',
-            dismiss_entities=("echo",),
+            dismiss_entities=dismiss_echo(),
         ),
         name="ds_confounds",
         run_without_submitting=True,

diff --git a/fmriprep/workflows/bold/confounds.py b/fmriprep/workflows/bold/confounds.py
@@ -40,6 +40,7 @@
     GatherConfounds,
     RenameACompCor,
 )
+from ...utils.bids import dismiss_echo
 
 
 def init_bold_confs_wf(
@@ -442,7 +443,7 @@ def init_bold_confs_wf(
     )
 
     ds_report_bold_rois = pe.Node(
-        DerivativesDataSink(desc="rois", datatype="figures", dismiss_entities=("echo",)),
+        DerivativesDataSink(desc="rois", datatype="figures", dismiss_entities=dismiss_echo()),
         name="ds_report_bold_rois",
         run_without_submitting=True,
         mem_gb=DEFAULT_MEMORY_MIN_GB,
@@ -461,7 +462,9 @@ def init_bold_confs_wf(
     )
 
     ds_report_compcor = pe.Node(
-        DerivativesDataSink(desc="compcorvar", datatype="figures", dismiss_entities=("echo",)),
+        DerivativesDataSink(
+            desc="compcorvar", datatype="figures", dismiss_entities=dismiss_echo()
+        ),
         name="ds_report_compcor",
         run_without_submitting=True,
         mem_gb=DEFAULT_MEMORY_MIN_GB,
@@ -473,7 +476,9 @@ def init_bold_confs_wf(
         name="conf_corr_plot",
     )
     ds_report_conf_corr = pe.Node(
-        DerivativesDataSink(desc="confoundcorr", datatype="figures", dismiss_entities=("echo",)),
+        DerivativesDataSink(
+            desc="confoundcorr", datatype="figures", dismiss_entities=dismiss_echo()
+        ),
         name="ds_report_conf_corr",
         run_without_submitting=True,
         mem_gb=DEFAULT_MEMORY_MIN_GB,
@@ -683,7 +688,7 @@ def init_carpetplot_wf(
     )
     ds_report_bold_conf = pe.Node(
         DerivativesDataSink(
-            desc="carpetplot", datatype="figures", extension="svg", dismiss_entities=("echo",)
+            desc="carpetplot", datatype="figures", extension="svg", dismiss_entities=dismiss_echo()
         ),
         name="ds_report_bold_conf",
         run_without_submitting=True,

diff --git a/fmriprep/workflows/bold/outputs.py b/fmriprep/workflows/bold/outputs.py
@@ -35,6 +35,7 @@
 from fmriprep import config
 from fmriprep.config import DEFAULT_MEMORY_MIN_GB
 from fmriprep.interfaces import DerivativesDataSink
+from fmriprep.utils.bids import dismiss_echo
 
 
 def prepare_timing_parameters(metadata: dict):
@@ -217,7 +218,7 @@ def init_func_fit_reports_wf(
             base_directory=output_dir,
             desc="summary",
             datatype="figures",
-            dismiss_entities=("echo",),
+            dismiss_entities=dismiss_echo(),
         ),
         name="ds_report_summary",
         run_without_submitting=True,
@@ -229,7 +230,7 @@ def init_func_fit_reports_wf(
             base_directory=output_dir,
             desc="validation",
             datatype="figures",
-            dismiss_entities=("echo",),
+            dismiss_entities=dismiss_echo(),
         ),
         name="ds_report_validation",
         run_without_submitting=True,
@@ -333,7 +334,7 @@ def init_func_fit_reports_wf(
                 desc="fmapCoreg",
                 suffix="bold",
                 datatype="figures",
-                dismiss_entities=("echo",),
+                dismiss_entities=dismiss_echo(),
             ),
             name="ds_sdcreg_report",
         )
@@ -355,7 +356,7 @@ def init_func_fit_reports_wf(
                 desc="sdc",
                 suffix="bold",
                 datatype="figures",
-                dismiss_entities=("echo",),
+                dismiss_entities=dismiss_echo(),
             ),
             name="ds_sdc_report",
         )
@@ -404,7 +405,7 @@ def init_func_fit_reports_wf(
             desc="coreg",
             suffix="bold",
             datatype="figures",
-            dismiss_entities=("echo",),
+            dismiss_entities=dismiss_echo(),
         ),
         name="ds_epi_t1_report",
     )
@@ -446,7 +447,7 @@ def init_ds_boldref_wf(
             desc=desc,
             suffix="boldref",
             compress=True,
-            dismiss_entities=("echo",),
+            dismiss_entities=dismiss_echo(),
         ),
         name="ds_boldref",
         run_without_submitting=True,
@@ -490,7 +491,7 @@ def init_ds_registration_wf(
             mode='image',
             suffix='xfm',
             extension='.txt',
-            dismiss_entities=('echo', 'part'),
+            dismiss_entities=dismiss_echo(["part"]),
             **{'from': source, 'to': dest},
         ),
         name='ds_xform',
@@ -535,7 +536,7 @@ def init_ds_hmc_wf(
             suffix="xfm",
             extension=".txt",
             compress=True,
-            dismiss_entities=("echo",),
+            dismiss_entities=dismiss_echo(),
             **{"from": "orig", "to": "boldref"},
         ),
         name="ds_xforms",
@@ -593,7 +594,7 @@ def init_ds_bold_native_wf(
             desc='brain',
             suffix='mask',
             compress=True,
-            dismiss_entities=("echo",),
+            dismiss_entities=dismiss_echo(),
         ),
         name='ds_bold_mask',
         run_without_submitting=True,
@@ -615,7 +616,7 @@ def init_ds_bold_native_wf(
                 compress=True,
                 SkullStripped=multiecho,
                 TaskName=metadata.get('TaskName'),
-                dismiss_entities=("echo",),
+                dismiss_entities=dismiss_echo(),
                 **timing_parameters,
             ),
             name='ds_bold',
@@ -640,7 +641,7 @@ def init_ds_bold_native_wf(
                 space='boldref',
                 suffix='T2starmap',
                 compress=True,
-                dismiss_entities=("echo",),
+                dismiss_entities=dismiss_echo(),
                 **t2star_meta,
             ),
             name='ds_t2star_bold',
@@ -726,7 +727,7 @@ def init_ds_volumes_wf(
             compress=True,
             SkullStripped=multiecho,
             TaskName=metadata.get('TaskName'),
-            dismiss_entities=("echo",),
+            dismiss_entities=dismiss_echo(),
             **timing_parameters,
         ),
         name='ds_bold',
@@ -769,7 +770,7 @@ def init_ds_volumes_wf(
             base_directory=output_dir,
             suffix='boldref',
             compress=True,
-            dismiss_entities=("echo",),
+            dismiss_entities=dismiss_echo(),
         ),
         name='ds_ref',
         run_without_submitting=True,
@@ -781,7 +782,7 @@ def init_ds_volumes_wf(
             desc='brain',
             suffix='mask',
             compress=True,
-            dismiss_entities=("echo",),
+            dismiss_entities=dismiss_echo(),
         ),
         name='ds_mask',
         run_without_submitting=True,
@@ -809,7 +810,7 @@ def init_ds_volumes_wf(
                 base_directory=output_dir,
                 suffix='T2starmap',
                 compress=True,
-                dismiss_entities=("echo",),
+                dismiss_entities=dismiss_echo(),
                 **t2star_meta,
             ),
             name='ds_t2star_std',
@@ -905,7 +906,7 @@ def init_bold_preproc_report_wf(
             base_directory=reportlets_dir,
             desc='preproc',
             datatype="figures",
-            dismiss_entities=("echo",),
+            dismiss_entities=dismiss_echo(),
         ),
         name='ds_report_bold',
         mem_gb=DEFAULT_MEMORY_MIN_GB,

diff --git a/fmriprep/workflows/bold/resampling.py b/fmriprep/workflows/bold/resampling.py
@@ -44,6 +44,7 @@
 
 from ...config import DEFAULT_MEMORY_MIN_GB
 from ...interfaces.workbench import MetricDilate, MetricMask, MetricResample
+from ...utils.bids import dismiss_echo
 from .outputs import prepare_timing_parameters
 
 
@@ -181,6 +182,7 @@ def select_target(subject_id, space):
         DerivativesDataSink(
             base_directory=output_dir,
             extension=".func.gii",
+            dismiss_entities=dismiss_echo(),
             TaskName=metadata.get('TaskName'),
             **timing_parameters,
         ),