No multi-echo (T2*, etc.) in the boilerplate text?

Software Support
,
1

Summary of what happened:

Short version: fmriprep (25.2.2) successfully preprocessed several sessions with multi-echo runs, including creating T2star derivatives images and T2* sections in the html report. However, the boilerplate text does not describe the multi-echo preprocessing, nor mention/cite tedana. Is this expected or a bug?

Longer version & background: The report for sessions with only multi-echo runs has a single “Functional data preprocessing” section, which has “First, a reference volume was generated from the shortest echo of the BOLD run, …” in the second sentence. Reports for sessions with both single-echo and (proper > 2 echo) multi-echo runs have two “Functional data preprocessing” sections, identical except that one includes the “from the shortest echo of the BOLD run” phrase. I was expected more multi-echo-specific description; is detailed multi-echo processing boilerplate elsewhere?

More broadly, is there a straightforward way to track fmriprep’s tedana workflow? For example, wf.bold_t2smap appears in the Node lists (in the command files we save) when a proper multi-echo run is preprocessed, but not for single-echo runs; is it safe to assume that no multi-echo processing occurred if wf.bold_t2smap is not present? This came up because of (ongoing) multi-echo tests, in which we include only a single echo (from a multi-echo run) in the BIDS dataset. If the single echo is included leaving “echo-1” in the filenames and jsons unchanged, the report summary includes “Multi-echo EPI sequence: only echo 1 processed in single-echo mode.”; if the files are renamed and EchoNumber field removed from the jsons, the summary is “Single-echo EPI sequence.” From what I can tell, this difference in the report summary is the only difference in the derivatives, but I was hoping to verify.

Thanks, and apologies for another lengthy question/comment!

Command used (and if a helper script was used, a link to the helper script or the command generated):

singularity run --cleanenv -B \
${PRIMARY_WORKING_DIR}${SUBID}:/tmp \
/scratch3/fmriprep-25.2.2.simg \
--fs-license-file /tmp/.license/freesurfer/license.txt \
-w /tmp /tmp/BIDS /tmp/derivatives \
participant --participant_label ${SUBID} \
--fs-subjects-dir /tmp/sourcedata/freesurfer  \
--output-spaces fsaverage:den-10k MNI152NLin2009cAsym \
--n-cpus 16 \
--omp-nthreads 4 \
--mem-mb 64000 -v >> ${PRIMARY_WORKING_DIR}${SUBID}/${SUBID}_fmriprep_singularity_VOLSURF.txt 2>&1

Version:

fmriprep 25.2.2

Environment (Docker, Singularity / Apptainer, custom installation):

singularity

Data formatted according to a validatable standard? Please provide the output of the validator:

You are using fMRIPrep-25.2.2, and a newer version of fMRIPrep is available: 25.2.3.
Please check out our documentation about how and when to upgrade:
https://fmriprep.readthedocs.io/en/latest/faq.html#upgrading
251126-17:46:30,349 cli INFO:
	 Telemetry system to collect crashes and errors is enabled - thanks for your feedback!. Use option ``--notrack`` to opt out.
251126-17:46:38,321 cli INFO:
	 Making sure the input data is BIDS compliant (warnings can be ignored in most cases).
bids-validator@1.14.10
e[32mThis dataset appears to be BIDS compatible.e[39m
        e[34me[4mSummary:e[24me[39m                e[34me[4mAvailable Tasks:e[24me[39m        e[34me[4mAvailable Modalities:e[39me[24m 
        22 Files, 1.24GB        rest                    MRI                   
        1 - Subject                                                           
        1 - Session

Relevant log outputs (up to 20 lines):

PASTE LOG OUTPUT HERE

Screenshots / relevant information:

2

I think this is an oversight. The fMRIPrep boilerplate should cite tedana and other relevant publications, as well as document any multi-echo-specific processing.

I think the best way to track it would be to set a workflow.__desc__ in init_bold_t2s_wf.

1 Like
3

I think the best way to track it would be to set a workflow.__desc__ in init_bold_t2s_wf.

Could that be done via a singularity container command-line argument? I’ve never gotten into the “guts” of fmriprep (or tedana, for that matter).

4

No, this is a change that needs to be made to the fMRIPrep code and will only have an impact once a new release is made.

5

Actually, I’m looking at the code now and there definitely is multi-echo processing-related information in the workflow description: fmriprep/fmriprep/workflows/bold/t2s.py at 350fc582d320cba6ffbc00cdfee8df2a8e9e79e0 · nipreps/fmriprep · GitHub. I don’t know why that information is missing from your boilerplate. Any chance you can share the CITATION.html file from one of your multi-echo fMRIPrep runs?

6

CITATION.html.txt (19.5 KB)
CITATION2.html.txt (25.8 KB)

The first is from a session with all multi-echo functional runs, the second session has both single and multi-echo runs. Thanks!

7

The relevant text is definitely missing, and I see it’s also missing from one of my own CITATION.html files.

I think I see the problem. It looks like the parent workflow where init_bold_t2smap_wf is run (init_bold_native_wf) is using a vanilla Nipype workflow object instead of the Niworkflows LiterateWorkflow. My guess is that having a regular Workflow between LiterateWorkflows prevents the embedded LiterateWorkflows’ descriptions from being compiled.

EDIT: I’ve opened an issue about this. Multi-echo processing-related text is not included in boilerplate · Issue #3576 · nipreps/fmriprep · GitHub

1 Like