Exclude echo entity from optimally combined derivatives

[tsalo]

Closes #3165.

Changes proposed in this pull request

• 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.

Documentation that should be reviewed

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (3c836e8) 72.28% compared to head (1253d28) 72.37%.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3166      +/-   ##
==========================================
+ Coverage   72.28%   72.37%   +0.08%     
==========================================
  Files          55       55              
  Lines        4085     4098      +13     
==========================================
+ Hits         2953     2966      +13     
  Misses       1132     1132              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[tsalo]

The test fails because of the following:

< sub-02/anat/sub-02_desc-brain_mask.json
< sub-02/anat/sub-02_desc-brain_mask.nii.gz
< sub-02/anat/sub-02_desc-preproc_T1w.json
< sub-02/anat/sub-02_desc-preproc_T1w.nii.gz
< sub-02/anat/sub-02_dseg.nii.gz
< sub-02/anat/sub-02_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5
< sub-02/anat/sub-02_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5
< sub-02/anat/sub-02_label-CSF_probseg.nii.gz
< sub-02/anat/sub-02_label-GM_probseg.nii.gz
< sub-02/anat/sub-02_label-WM_probseg.nii.gz
22a13
> sub-02/anat/sub-02_space-MNI152NLin2009cAsym_desc-preproc_dseg.nii.gz
25,28c16,18
< sub-02/anat/sub-02_space-MNI152NLin2009cAsym_dseg.nii.gz
< sub-02/anat/sub-02_space-MNI152NLin2009cAsym_label-CSF_probseg.nii.gz
< sub-02/anat/sub-02_space-MNI152NLin2009cAsym_label-GM_probseg.nii.gz
< sub-02/anat/sub-02_space-MNI152NLin2009cAsym_label-WM_probseg.nii.gz
---
> sub-02/anat/sub-02_space-MNI152NLin2009cAsym_label-CSF_desc-preproc_probseg.nii.gz
> sub-02/anat/sub-02_space-MNI152NLin2009cAsym_label-GM_desc-preproc_probseg.nii.gz
> sub-02/anat/sub-02_space-MNI152NLin2009cAsym_label-WM_desc-preproc_probseg.nii.gz
36,37d25
< sub-02/func/sub-02_task-cuedSGT_run-01_desc-brain_mask.json
< sub-02/func/sub-02_task-cuedSGT_run-01_desc-brain_mask.nii.gz
44,49d31
< sub-02/func/sub-02_task-cuedSGT_run-01_echo-1_desc-preproc_bold.json
< sub-02/func/sub-02_task-cuedSGT_run-01_echo-1_desc-preproc_bold.nii.gz
< sub-02/func/sub-02_task-cuedSGT_run-01_echo-2_desc-preproc_bold.json
< sub-02/func/sub-02_task-cuedSGT_run-01_echo-2_desc-preproc_bold.nii.gz
< sub-02/func/sub-02_task-cuedSGT_run-01_echo-3_desc-preproc_bold.json
< sub-02/func/sub-02_task-cuedSGT_run-01_echo-3_desc-preproc_bold.nii.gz
60,61d41
< sub-02/func/sub-02_task-cuedSGT_run-01_space-MNI152NLin2009cAsym_T2starmap.json
< sub-02/func/sub-02_task-cuedSGT_run-01_space-MNI152NLin2009cAsym_T2starmap.nii.gz

From what I can tell, the T2starmap and echo-wise outputs are not generated, which is what I would expect. However, the other functional outputs don't have the echo entity, which means that the outputs are not correctly named when using --echo-idx.

I'm not sure why there are differences in the anatomical outputs.

EDIT: Ah, I think I understand why native-space outputs weren't generated when --echo-idx was used. It must be because of --me-output-echos!

Still, why did the MNI152NLin2009cAsym-space dseg and probseg files have desc-preproc when --echo-idx was used, but no desc field when it wasn't?

[effigies]

I'm not in love with the name. The intuitive meaning of dismiss_echo(["part"]) is not obviously ["part", "echo"] or ["part"], but I also haven't come up with a better name for the function. We can change the name if it ever becomes necessary.

[madisoth]

Just tested this and can confirm it ran without issues.

[tsalo]

Thanks @madisoth!