MEDIC phase-unwrapping IndexError on OpenNeuro ds006072/sub-P1R

[DVSneuro]

Hi @vanandrew -- following up from nipreps/fmriprep#3645.

I tested MEDIC/warpkit through the fMRIPrep integration branch on OpenNeuro ds006072, version 1.0.8, subject sub-P1R. The run starts MEDIC workflows, but fails during phase unwrapping with an IndexError.

I checked the simple BIDS pairing/shape possibility first. For sub-P1R, all 19 multi-echo BOLD run groups have matching part-mag and part-phase files, matching echo sets 1-5, and matching 4D shapes within each run. REST runs are (110, 110, 72, 516) and TASK runs are (110, 110, 72, 225) for both mag and phase.

The first failing node in my log was:

sub-P1R_ses-3_task-BOLDTASK1_dir-PA_run-1

Unless I'm missing something, I think relevant error stack is:

File ".../warpkit/unwrap.py", line 283, in unwrap_phase
    combined_mask = get_largest_connected_component(combined_mask)

File ".../warpkit/utilities.py", line 182, in get_largest_connected_component
    mask_data = labelled_mask == sorted_props[0].label

IndexError: list index out of range

This is then re-raised by warpkit/distortion.py as:

IndexError: An IndexError was encountered while unwrapping phase images.
This tends to happen if you have noise frames left in your data.

Full fMRIPrep/warpkit log is here: ds006072_v1_0_8_sub-P1R_run-20260509-222518_fmriprep-warpkit.log

Thanks!
David

[vanandrew]

@DVSneuro It looks like the last 3 frames in ds006072 are noise frames (see my attached frame 221 vs. frame 222). Some multi-echo scans have noise frames at the end for denoising methods, but these aren't usable data and it causes masking logic in MEDIC to fail. I have a noise_frames argument to ignore these frames at the end.

By default, the noise frames argument is 0, but you should set it to 3 for this dataset (I took this from Line 63 - 73 of fmriprep/interfaces/warpkit.py in your nipreps/fmriprep#3645 PR):

        result = medic(
            phase=self.inputs.phase,
            magnitude=self.inputs.magnitude,
            out_prefix=out_prefix,
            tes=self.inputs.tes,
            total_readout_time=self.inputs.total_readout_time,
            phase_encoding_direction=self.inputs.phase_encoding_direction,
            n_cpus=self.inputs.n_cpus,
            noise_frames=3,  # <-- Add this argument for this dataset
            wrap_limit=self.inputs.wrap_limit,
            debug=self.inputs.debug,
        )

Give this a try and let me know if this fixes it for this dataset.

Frame 221

Frame 222

[DVSneuro]

Thanks @vanandrew ! That was indeed the problem and fixed the issue. I added a cli option to that pull request (--me-warpkit-noise-frames; nipreps/fmriprep@4eb308f).

Seems to work well, and seems like something users might want in an integration with fmriprep. Thanks again!

Log is here in case it's helpful:

ds006072_v1_0_8_sub-P1R_run-20260511-132325_fmriprep-warpkit.log