Omnibus multi-echo pull request

[effigies]

This PR tracks a series of updates to multi-echo preprocessing, an effort being led by @emdupre. The work has been broken into multiple PRs to ensure that each is independently reviewable.

New multi-echo related PRs should target the multiecho branch of the main repository, rather than master.

Any updates to master should be merged into multiecho as soon as possible to avoid getting out of sync.

Refactors that substantially affect the BOLD workflows should consider targeting the multiecho branch unless updates to master are needed before multiecho is likely to be merged.

Changes proposed in this pull request

Closes #1034, #1135

• [ENH] Update ME-EPI workflow to create optimal combination #1263 (signed off by @effigies)
• [ENH] Add echo-idx flag #1355 (signed off by @effigies)
• [ENH] Use standard T2* map as coregistration target #1383 (signed off by @oesteban)

[emdupre]

I'm a little confused how merging in a pull request to merge in master resulted in new merge conflicts ! Do you want me to try and fix the conflict here, @effigies ?

[effigies]

It was fine, but there've since been changes to master. I think if we wait for #1354, the conflicts will go away again.

[emdupre]

@effigies Looking back at previous conversations from #1324 (comment), how would I go about modifying bbregister parameters ? Did you want me to loop in someone, or should I test them myself ? Or should we instead follow previous suggestions from @oesteban (see: #1034) and modify the T2* map itself ?

[effigies]

Ah, reading #1034, it might be good to get ahold of a "failing" T2* map to see if we can assess the issues. If we're confident that it's not negative numbers and outliers, then we can go ahead and ping the FreeSurfer list to see if there are any tweakable parameters to try for bbregister. Are you comfortable experimenting with the directions @oesteban suggested? Also happy to provide more specific suggestions.

[emdupre]

Yes, happy to. It looks like merging in master broke something here, though, so maybe I'll try to fix that first !

[effigies]

Ah, thanks for the heads up. I also apparently failed to read you saying you'd fix it, so I think I fixed it.

[emdupre]

I had pushed this off until I had a little more time to sit down with it, but the solution was actually easier than I originally anticipated.

Essentially, when calculating the T2* map we have the problem of what to do in voxels where only one echo has reliable signal. For the standard T2* map we simply exclude those voxels, as their values can be unpredictable. For the adaptive T2* map-- which I had originally set as the coregistration target in the case of -t2s-coreg we retain them and treat them at face value.

When I switched to the more stable, "standard" T2* map, the 10% cases vanished. The poorly behaving example I had shown previously (among others) now looks as expected, see:

I've opened #1383 to address this change and to make sure that the reports and all other relevant documentation is up-to-date. But I'm feeling optimistic that this is quite close !

[effigies]

Sounds good to me.