ENH: Add optional warpkit MEDIC support for multi-echo BOLD distortion correction

[DVSneuro]

Changes proposed in this pull request

I think this is a little related to #3336 and maybe some other work from @tsalo , but this PR addresses a narrower use case than that issue: optional MEDIC-based susceptibility distortion correction for compatible multi-echo BOLD runs with part-phase data, using warpkit following the logic from Andrew Van's ( @vanandrew ) preprint on bioRxiv: https://www.biorxiv.org/content/10.1101/2023.11.28.568744v1

When --me-use-warpkit is enabled, fMRIPrep will:

• identify eligible multi-echo BOLD runs with corresponding part-phase data
• estimate a time-varying B0 fieldmap series with MEDIC from phase evolution across echoes
• use that fieldmap series during resampling
• report the run as MEDIC (warpkit) in the functional summary

This path is opt-in and does not change default behavior for existing workflows.

Main changes in this PR:

• add a new CLI/config option: --me-use-warpkit
• add an interface for calling warpkit.api.medic
• wire MEDIC into the multi-echo BOLD workflow for eligible runs
• ensure MEDIC-managed runs do not also use standard fmap selection for the same run
• add support for applying a 4D fieldmap series volume-by-volume during resampling
• add reportlets for a representative fieldmap view and an SDC before/after panel
• add citation/boilerplate text describing the MEDIC-based correction path
• add tests covering parser/config behavior, workflow wiring, BIDS helpers, and resampling behavior

Current scope / limitations:

• this feature is opt-in
• it is currently intended for compatible multi-echo datasets with part-phase companions
• MEDIC-managed runs currently prefer the MEDIC path rather than falling back to standard fieldmaps for the same run
• report output currently includes representative static views rather than a time-resolved QC plot of the full 4D fieldmap series

Validation performed:

• targeted unit/workflow tests for the new CLI flag, interface wiring, BIDS helpers, and 4D fieldmap resampling
• container build including warpkit
• smoke testing of the containerized import path
• a real multi-echo dataset with phase data from OpenNeuro (https://openneuro.org/datasets/ds005123/versions/1.1.3), confirming successful execution and report generation

In the HTML report, warpkit-enabled runs showed:

• Susceptibility distortion correction: MEDIC (warpkit)
• a representative fieldmap reportlet
• an SDC before/after reportlet

This is my first contribution to fMRIPrep, so I tried to keep the scope focused and follow existing workflow patterns closely.

I used OpenAI Codex to help draft and iterate on portions of the code and tests, and I manually reviewed and tested the resulting changes as carefully as I could, but I wouldn't say I'm an expert on this (maybe a little better than vibe coding, but not by much).

Documentation that should be reviewed

This PR does not add standalone user documentation pages, but it does update user-facing/report-facing text in a few places:

• a new CLI option, --me-use-warpkit
• functional reportlets for the MEDIC/warpkit path
• citation/boilerplate text describing the MEDIC-based distortion-correction procedure

[welcome]

Thanks for opening this pull request! It looks like this is your first time contributing to fMRIPrep. 😄
We invite you to list yourself as an fMRIPrep contributor. To learn more about what that entails and how we credit our contributors, please check out the contributing guidelines. If your name is not already on the list, please insert it, in alphabetical order, into the CONTRIBUTORS.md file.
Of course, if you want to opt-out this time there is no problem at all with adding your name later. You will be always welcome to add it in the future whenever you feel it should be listed.

[effigies]

This is extremely interesting and coincides with some work by @vanandrew in sdcflows (note to self: link PR). I've been meaning to look into how it would integrate and haven't found the time.

Have you run datasets with this workflow? Do the results look good to you? Do you have comparisons with other fieldmap types?

I will try to look at this in some detail soon.

[DVSneuro]

I've only ran a couple of subjects from our dataset (https://openneuro.org/datasets/ds005123/versions/1.1.3), and here's one example visualization for a single time point, which looks pretty good to me.

I haven't compared it directly with standard fieldmaps, though we have those in the dataset above.

We were drawn to warpkit/medic since some of our participants move a lot (older adults) and we had a few cases where the participant needed to get out of the scanner for a break but we forgot to get a new fieldmap when they got back in. So, the idea of making the fieldmaps for each frame using the multi-echo phase data was very appealing to us! But when we first started using medic/warpkit a year or so ago, I couldn't figure out how to get it integrated into fmriprep, so we'd generate a fieldmap for the first time point of each run and use that in the normal fmriprep workflow and the results have been good. I'm assuming the framewise implementation should be even better, especially for high-motion participants -- but hopefully I didn't break anything or do anything too silly with this PR!

[vanandrew]

I got you @effigies: nipreps/sdcflows#541 :)

I haven't reviewed @DVSneuro PR yet, but my vague plan was to have MEDIC be called from sdcflows via init_fmap_preproc_wf (this line in fmriprep).

On the fmriprep side, the biggest changes would need to be in how the field map is applied: in MEDIC, you get a field map for every frame of your scan, so the one step resampling would need to be adjusted to account for this. Given that @DVSneuro has some results, I assume your PR already makes a change like this?

Awesome job getting this working btw :).

[DVSneuro]

Thanks @vanandrew ! I had plenty of help from Codex. And yes, this PR does update the fMRIPrep side so a 4D MEDIC fieldmap series is applied volume-by-volume during one-step resampling. The current implementation calls MEDIC directly from fMRIPrep, but I’d be open to trying to restructure that piece if the preferred long-term architecture is to generate the MEDIC estimates in sdcflows and then consume them from fMRIPrep.

I'm not seeing any other multi-echo datasets on OpenNeuro that have the phase data, so the testing here has been somewhat limited.

[tsalo]

@DVSneuro, I suggest checking https://me-ica.github.io/open-multi-echo-data/. I try to keep it up to date, and you can filter by if there's complex-valued data or not.

There are nine on OpenNeuro that I'm aware of:

• https://openneuro.org/datasets/ds007637
• https://openneuro.org/datasets/ds007486
• https://openneuro.org/datasets/ds006926
• https://openneuro.org/datasets/ds006707
• https://openneuro.org/datasets/ds006131
• https://openneuro.org/datasets/ds006072
• https://openneuro.org/datasets/ds005123
• https://openneuro.org/datasets/ds005085
• https://openneuro.org/datasets/ds002278

I think the goal should be to have MEDIC within SDCFlows so that dynamic distortion correction is treated like static distortion correction, though it would be cool if fMRIPrep could use wk-unwrap-phase to produce unwrapped phase data in any desired output spaces.

One change that might be necessary on fMRIPrep's side is (optionally?) swapping the order of HMC and SDC when MEDIC is used, since I think dynamic distortion correction should improve motion correction.

[vanandrew]

For datasets, I've mostly been using this one for my own tests: https://openneuro.org/datasets/ds006926/versions/1.0.0 (was the only public dataset I could find that has both mag/phase).

Getting into some of the more technical details:

• The plan is to have [WIP] [FEAT] MEDIC distortion correction via warpkit sdcflows#541 emit fmap_dynamic* fields from init_fmap_workflow_wf.
• This fieldmap dynamic file is a 4D nifti, where each frame contains a fieldmap in Hz (so extracting a single frame would be equivalent to the regular fmap output).
• @tsalo suggestion for swapping HMC/SDC, that's definitely worth considering. I don't think I looked into this in my original paper. I'm not sure how much work that is though, so it might be worth shifting into another PR.

Side question: I noticed that both nipreps project currently support python version 3.10+, but I've made warpkit support 3.11+ (mainly because 3.10 is due to be deprecated in October this year). It is worth lowering the python version requirement for warpkit? I wasn't sure how long you guys support deprecated python versions.