MAINT: Merge master into multiecho

[effigies]

Master is conflicting with multiecho.

[emdupre]

Sorry for the lag on this ! Here's a sketch of where I think we are right now, and where I'd like this to go:

Background

With #1263, we addressed a couple of points:

• Previously, we were duplicating tedana code for the creation of a T2* map; that is now imported from tedana directly and wrapped in a nipype style interface.
• All echos were previously iterated over individually, with two exceptions. (1) at head motion correction, where only the first echo was used, and (2) at coregistration, where the T2* map was created jointly and used to coregister all echos. Now, all echos are only iterated in one sub-workflow. The T2* map and the optimally combined time series (a weighted average of the echos) are created, and the optimal combination is treated as the primary BOLD file and returned to the user.
• We made initial modifications to the documentation to discuss this update.

There are a few things that I think still need to be done to finish this line of work, with a main aim being that multi-echo series will return the optimal combination by default, in the future with optional TE-informed denoising.

Roadmap

• In completing [ENH] Update ME-EPI workflow to create optimal combination #1263, we noticed that there are a number of cases (I'd estimate 10%, from running a few subjects locally), where the generated T2* map shows significant distortions only in surface space. See below for an example:

This needs to be addressed before merging. I know @effigies and I spent some time looking into this a few weeks back, but I feel like we decided against it being q- or s-form codes. Suggestions are greatly appreciated !

• The documentation and the boilerplate both need to be fully updated to reflect these changes. Should we add in a multi-echo citation, and the tedana citation ? What is the recommendation, here ?

• I'd like to add an additional flag, like --task-id, for --echo-number. This would allow users to treat a multi-echo series as a single-echo acquisition by only selecting for processing those echos which they want back. A common use case would be selecting only the echo closest to 30ms for processing to approximate results from a single-echo acquisition.

Happy to add or edit points as you think is appropriate ! Thanks so much as always for you support ✨

[effigies]

• bbregister - My best guess is that the T2* map has higher than usual non-uniformities in the white matter, causing mri_segreg (the bbr part of bbregister) to prefer a random blob over the gray/white boundary. This might be worth working directly with Doug to see if we can find a set of parameters (or do a preprocessing step to mask/impute outlier voxels to avoid over-fitting) for bbregister that will work with your 10% (and not damage the 90%).

• Citations - I tried to cite both the tools and, when a method was directly discussed, the first paper I could find to introduce it. Or if the authors of a tool have specific papers they suggest citing, I followed that guidance. So I guess in tedana's case, it's your call.

• --echo-index? Or --echo-id or --echo-idx? Any seems fine to me. I think such a selector is perfectly reasonable.

[effigies]

@emdupre I had a look through this, and I don't think anything interferes with the changes currently in #1296. Could you do another (quick) read through, since I merged in master?

[emdupre]

From a read-through the added merge seems fine ! We'll see if any conflicts creep in ...
I'm at a conference so I'll be in and out for a few days. But, I'm looking forward to seeing this done ! @oesteban if you or @chrisfilo have feedback on the next steps I outlined please let me know !