Multi-echo derivatives

[effigies]

• T2* map (space boldref?)
• All echos, with STC+HMC+SDC applied (new flag)
• Decompositions
  • _mixing.tsv separate from _desc-confounds_timeseries.tsv
  • _metrics.tsv + json (non-BEP-012)

cc @jbteves @tsalo @eurunuela for verification

[effigies]

• T2* map (space boldref?)

The T2* map is the boldref as of #2547, which will be in 21.0.0. I think by BIDS, we should change the suffix to T2starmap in the multi-echo case.

[effigies]

• All echos, with STC+HMC+SDC applied (new flag)

Let's call this space T2starmap, and we will always want it if individual echos are requested. If that's the case, would we also want the optimal combination in this space, or is it possible that we'd want the OC in T1w or MNI, but not in T2starmap?

Just trying to figure out the branching logic that we're going to need and how many flags will be needed to cover the range of plausible outputs.

[tsalo]

The T2* map shouldn't be the boldref since we removed that option in #2109, right?

[effigies]

Do you want to check #2547? I'm not sure if we re-did that or not, but it's definitely what's set to be saved as a _boldref.nii.gz image.

[tsalo]

You're right. For posterity, here it is:

fmriprep/fmriprep/workflows/bold/base.py

Lines 1005 to 1008 in a02c1c1

	(bold_t2s_wf, bold_final, [
	("outputnode.bold", "bold"),
	("outputnode.t2star_map", "boldref"),
	]),

I'm not sure why that was done. In #2181, we started calculating the final boldref based on the first echo's STC+MCed data (i.e., post-bold_bold_trans_wf), since that echo would have the most brain coverage.

fmriprep/fmriprep/workflows/bold/base.py

Lines 574 to 575 in 5e291b8

	(join_echos, final_boldref_wf, [
	('bold_files', 'inputnode.bold_file')]),

We stopped using the T2* map because, while it was originally thought to have better contrast (hence the old --t2s-coreg option), it ended up not performing very well. @emdupre does that sound right?

BTW, to respond to your other question:

Let's call this space T2starmap, and we will always want it if individual echos are requested. If that's the case, would we also want the optimal combination in this space, or is it possible that we'd want the OC in T1w or MNI, but not in T2starmap?

I don't think there's a strong reason to have the OC data in the T2starmap/boldref space, since it's (1) easy enough to calculate when you have the echoes, echo times, and T2* map, and (2) tedana doesn't actually allow you to provide the OC data when you're running the classification workflow on an existing mixing matrix, due to (1). So it won't be much use. That said, if it doesn't add many LOC, then I don't see the harm.

[effigies]

Okay, so we should revert the t2star_map -> boldref change and these will be two separate derivatives as well.

Would people just want the raw T2* map or transformed into the --output-space-declared spaces, or both?

Regarding the OC, it's not really a question of LOC, and the harm would be space wasted on an unwanted derivative. So the upshot of my question and your answer is that we shouldn't use --output-spaces T2starmap to decide that we want the cleaned echos since people are unlikely to want all of the consequences of that. Let's assume we'll go with something like --bold-echos.

So let's suppose I have --output-spaces anat --bold-echos, I should get something like:

sub-01/func/sub-01_task-rest_space-anat_boldref.nii.gz
sub-01/func/sub-01_task-rest_space-anat_desc-preproc_bold.nii.gz
sub-01/func/sub-01_task-rest_space-orig_T2starmap.nii.gz
sub-01/func/sub-01_task-rest_echo-1_space-orig_desc-preproc_bold.nii.gz
sub-01/func/sub-01_task-rest_echo-2_space-orig_desc-preproc_bold.nii.gz
sub-01/func/sub-01_task-rest_echo-3_space-orig_desc-preproc_bold.nii.gz

Seem reasonable? (Might need to do something other than orig. I'll check the spec.)

[effigies]

So it looks like we're performing SDC on the optimal combination, rather than on the individual echos prior to T2*-map estimation.

To get STC+HMC+SDC echos, we can either apply the SDC to the echos after the fact (and I guess the T2* map), or we can pass in SDC'd time series to Tedana.

What is the Tedana best practice here?

[tsalo]

Would people just want the raw T2* map or transformed into the --output-space-declared spaces, or both?

The main benefit is in running tedana, but it can also be useful for QC. I don't know if that QC needs to be in standard space, but it could help. That said, I don't think it's a big deal if the T2* map is just in boldref space. @handwerkerd do you think a standard space T2* map would be necessary?

The outputs you list seem reasonable, though having the brain mask in orig space would be very helpful.

What is the Tedana best practice here?

We currently recommend using non-SDCed data in tedana, but we don't have any actual tests comparing pre-SDC vs post-SDC. I have been using the SDCed data in my own analyses, because it's easier to take STC+MC+SDCed data, run it through tedana, and then apply the necessary transforms than to grab the data before SDC. If it's easy enough to run tedana within fMRIPrep before SDC, then I'd lean slightly toward that.

[effigies]

So when you get your individual echo derivatives, you would want them STC+HMC but not SDC'd? And similarly, the T2* map should not be SDC'd?

But your optimal combinations should still be SDC'd?

Would you also need the SDC warp (I think we should do this, but it will affect priorities) to be output?

[handwerkerd]

Since I'm not an fMRIprep user, I don't completely follow the specific issue at hand here. If I get the part where you're asking me a question, it's whether there might be a need to allow someone to input a T2* map that isn't generated directly from the multi-echo time series data? That is currently a viable option in tedana. I don't know if anyone has specifically evaluated if it's better or worse. My sense it that there will be situations where a separately acquired, more empirical T2* map would be useful.