Repository navigation
Conversation
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #541 +/- ##
==========================================
+ Coverage 84.13% 85.70% +1.56%
==========================================
Files 30 33 +3
Lines 2938 3175 +237
Branches 401 458 +57
==========================================
+ Hits 2472 2721 +249
+ Misses 388 373 -15
- Partials 78 81 +3 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
57ccc47 to
21ab1c6
Compare
bcaf4ad to
9ecfbae
Compare
Three additions targeting the codecov/patch failure on nipreps#541: * sdcflows/interfaces/tests/test_warpkit.py (new) — instantiates every warpkit-backed interface so its spec class body is hit at import (was 0% on codecov despite running locally; likely an xdist worker-merge artefact). Also covers ``_as_str_list``, the ``_pkg`` invariant, and the ``border_filt=(1, 5)`` traits default regression. * sdcflows/workflows/tests/test_outputs.py (new) — direct construction test for ``init_fmap_derivatives_wf``, exercising both the default and ``write_dynamic=True`` paths. The MEDIC dynamic sinks branch was only reached transitively from the ``test_fmap_wf`` slow test, hence 0% patch coverage on outputs.py. * sdcflows/workflows/fit/tests/test_medic.py — fill the remaining helper gaps: empty-metadata rejection, ``sloppy=True`` zooms_min, ``_first``, and ``_temporal_mean`` for both 3D and 4D inputs. The ``_run_interface`` method bodies in interfaces/warpkit.py remain uncovered in the fast/slow envs since they require warpkit to import; the existing ``veryslow`` MEDIC fixtures exercise them when the optional dependency is installed.
|
I have no idea why test (3.13, pre, fast) is failing on the cache step. It looks like an out-of-space error on the runner (but the other jobs with the same steps succeeded, so very confused): |
|
@vanandrew I think someone must have rerun that failing job and now it's passing. |
tsalo
left a comment
There was a problem hiding this comment.
Thanks for this! I made a quick pass through the code.
|
Pushed four commits addressing your feedback (noise_frames, ctor inputs, nitransforms switch + interface cleanup, unified fmap output). |
|
I can't tell if these test failures are something wrong with my dataset additions or if it's just another one-off error: |
a4c4781 to
b070878
Compare
|
Looks like the CI keeps failing because it's running out of space (I added two datasets for tests so that might have pushed it over the edge). I pushed 6f5cfff2 adding a - name: Free disk space
uses: jlumbroso/free-disk-space@main
with:
tool-cache: false
android: true
dotnet: true
haskell: true
large-packages: false
swap-storage: falseThis gets rid of some unneeded development tools on the github runner to free room for data. |
|
@tsalo Alright. I made changes based on our convo today:
|
Three additions targeting the codecov/patch failure on nipreps#541: * sdcflows/interfaces/tests/test_warpkit.py (new) — instantiates every warpkit-backed interface so its spec class body is hit at import (was 0% on codecov despite running locally; likely an xdist worker-merge artefact). Also covers ``_as_str_list``, the ``_pkg`` invariant, and the ``border_filt=(1, 5)`` traits default regression. * sdcflows/workflows/tests/test_outputs.py (new) — direct construction test for ``init_fmap_derivatives_wf``, exercising both the default and ``write_dynamic=True`` paths. The MEDIC dynamic sinks branch was only reached transitively from the ``test_fmap_wf`` slow test, hence 0% patch coverage on outputs.py. * sdcflows/workflows/fit/tests/test_medic.py — fill the remaining helper gaps: empty-metadata rejection, ``sloppy=True`` zooms_min, ``_first``, and ``_temporal_mean`` for both 3D and 4D inputs. The ``_run_interface`` method bodies in interfaces/warpkit.py remain uncovered in the fast/slow envs since they require warpkit to import; the existing ``veryslow`` MEDIC fixtures exercise them when the optional dependency is installed.
da9d07b to
c55efd0
Compare
Three additions targeting the codecov/patch failure on nipreps#541: * sdcflows/interfaces/tests/test_warpkit.py (new) — instantiates every warpkit-backed interface so its spec class body is hit at import (was 0% on codecov despite running locally; likely an xdist worker-merge artefact). Also covers ``_as_str_list``, the ``_pkg`` invariant, and the ``border_filt=(1, 5)`` traits default regression. * sdcflows/workflows/tests/test_outputs.py (new) — direct construction test for ``init_fmap_derivatives_wf``, exercising both the default and ``write_dynamic=True`` paths. The MEDIC dynamic sinks branch was only reached transitively from the ``test_fmap_wf`` slow test, hence 0% patch coverage on outputs.py. * sdcflows/workflows/fit/tests/test_medic.py — fill the remaining helper gaps: empty-metadata rejection, ``sloppy=True`` zooms_min, ``_first``, and ``_temporal_mean`` for both 3D and 4D inputs. The ``_run_interface`` method bodies in interfaces/warpkit.py remain uncovered in the fast/slow envs since they require warpkit to import; the existing ``veryslow`` MEDIC fixtures exercise them when the optional dependency is installed.
c55efd0 to
b0a6904
Compare
|
@tsalo I did a rebase to the latest main, hopefully to quash the 3.13 test error that happened in the last CI run: https://github.com/nipreps/sdcflows/actions/runs/26792754492/job/79155816998#step:22:320 |
Three additions targeting the codecov/patch failure on nipreps#541: * sdcflows/interfaces/tests/test_warpkit.py (new) — instantiates every warpkit-backed interface so its spec class body is hit at import (was 0% on codecov despite running locally; likely an xdist worker-merge artefact). Also covers ``_as_str_list``, the ``_pkg`` invariant, and the ``border_filt=(1, 5)`` traits default regression. * sdcflows/workflows/tests/test_outputs.py (new) — direct construction test for ``init_fmap_derivatives_wf``, exercising both the default and ``write_dynamic=True`` paths. The MEDIC dynamic sinks branch was only reached transitively from the ``test_fmap_wf`` slow test, hence 0% patch coverage on outputs.py. * sdcflows/workflows/fit/tests/test_medic.py — fill the remaining helper gaps: empty-metadata rejection, ``sloppy=True`` zooms_min, ``_first``, and ``_temporal_mean`` for both 3D and 4D inputs. The ``_run_interface`` method bodies in interfaces/warpkit.py remain uncovered in the fast/slow envs since they require warpkit to import; the existing ``veryslow`` MEDIC fixtures exercise them when the optional dependency is installed.
71f7ba7 to
aab352e
Compare
aab352e to
5614b98
Compare
|
I did a reorg of the git history for this since it was getting kind of intractable (~60 commits -> 8 commits). Also, rebased everything to the latest main branch. |
5614b98 to
bb04871
Compare
bb04871 to
8923a4e
Compare
|
Thanks. This is still on my to-do list. I think we're realistically going to need to focus on preserving old behavior and allow users to detect bugs in the new stuff, because I don't know that I have the bandwidth to review this as carefully as I would like. |
|
@effigies Alright. Then I'll work on re-implementing this as an optional separate pathway, while preserving the original code. |
|
@vanandrew Sorry, I didn't mean to imply that. I think keeping it as one pathway makes sense, and my review will just focus less on the correctness of the 4D branches and ensure the 3D branches are still doing what's expected. |
8923a4e to
466802f
Compare
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
MEDIC has confirmed workflow-construction and reporting failures, and its dependency packaging contradicts the stated opt-in design.
Review effort: Balanced
Findings: 7
Open (13)
Forward no_medic in normal CLI execution · New Validate matching phase and magnitude echoes · New Skip coefficient outputs for dynamic estimators · New Validate pre-gridded map shape and affine · New Bound queued coordinate-grid task memory · New Seed outer MEDIC inputs from the estimator · New Provide matching 3D MEDIC report inputs · New Move warpkit to an opt-in extra · New Implement the missing force_medic discovery path · New Apply session filters to identifier file lookups · New Preserve IntendedFor MEDIC runs with other identifiers · New Pass omp_nthreads to warpkit interfaces · New Compute each echo's readout time with get_trt · New
What changed in this PR
This PR adds MEDIC fieldmap estimation and per-volume distortion correction to sdcflows for multi-echo magnitude and phase data.
Changes:
- Adds MEDIC detection, warpkit interfaces, and a fieldmap estimation workflow.
- Adds 4D fieldmap resampling and connects it to derivative and report workflows.
- Adds tests and CI fixtures; the current packaging makes warpkit a required dependency rather than the described opt-in extra.
| File | Description |
|---|---|
sdcflows/workflows/tests/test_outputs.py |
Checks 4D fieldmap merge configuration. |
sdcflows/workflows/outputs.py |
Allows 4D fieldmaps in derivative output. |
sdcflows/workflows/fit/tests/test_medic.py |
Tests MEDIC construction and metadata handling. |
sdcflows/workflows/fit/medic.py |
Builds the MEDIC estimation workflow. |
sdcflows/workflows/base.py |
Connects dynamic estimators to preprocessing outputs. |
sdcflows/workflows/apply/tests/test_dynamic.py |
Tests dynamic apply construction and resampling. |
sdcflows/workflows/apply/dynamic.py |
Adds the per-volume correction workflow. |
sdcflows/utils/wrangler.py |
Discovers and orders MEDIC estimators. |
sdcflows/utils/tests/test_wrangler.py |
Tests MEDIC discovery and opt-out behavior. |
sdcflows/transform.py |
Supports per-frame fieldmaps in resampling. |
sdcflows/tests/test_fieldmaps.py |
Tests MEDIC estimator validation. |
sdcflows/interfaces/warpkit.py |
Wraps warpkit’s estimation stages. |
sdcflows/interfaces/tests/test_warpkit.py |
Checks warpkit interface specifications. |
sdcflows/fieldmaps.py |
Adds the MEDIC estimator type and workflow dispatch. |
sdcflows/conftest.py |
Provides MEDIC test fixtures. |
sdcflows/config.py |
Adds MEDIC opt-out configuration. |
sdcflows/cli/parser.py |
Adds the --no-medic option. |
sdcflows/cli/main.py |
Passes the option through dry-run discovery. |
pyproject.toml |
Adds warpkit as a dependency. |
.zenodo.json |
Adds contributor metadata. |
.github/workflows/build-test-publish.yml |
Fetches MEDIC test data in CI. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Generalize _resample_with_fieldmap so a per-volume (4D) fieldmap runs through the same code path as a static 3D one, selecting the matching frame for each volume. fieldmap_jacobian now takes the voxel shift map directly instead of recomputing it, so the static and dynamic callers share a single definition. Document the fmap_hz preconditions.
Add UnwrapPhase and ComputeFieldmap, wrapping warpkit's multi-echo phase unwrapping and fieldmap computation. Both follow the nipype num_threads convention. warpkit becomes a core dependency (>= 1.5.0). It carries a Washington University non-commercial license, so commercial use requires a separate WUSTL OTM agreement.
Add EstimatorType.MEDIC together with the is_dynamic property that tells per-volume fieldmaps apart from static ones. MEDIC estimation validates its file set up front, rejecting incomplete magnitude/phase part sets and single-echo input rather than failing deep inside the workflow.
Discover MEDIC estimators from B0FieldIdentifier and IntendedFor metadata only, never from directory structure alone. Cover the magnitude side of IntendedFor and de-duplicate estimators that both fields point at. Add --no-medic to opt out of MEDIC discovery entirely.
Fit workflow chaining UnwrapPhase into ComputeFieldmap to produce a per-volume fieldmap from complex multi-echo BOLD. fmap_ref comes from the raw first-echo magnitude and fmap_mask from warpkit's masks by way of init_dynamic_magnitude_wf, so dynamic estimators expose the same outputs as static ones.
Apply workflow that unwarps a BOLD series volume by volume against its per-volume fieldmap, with Jacobian intensity correction and the phase-encoding direction sign forwarded through to the fieldmap conversion. Resampling goes through nitransforms.
…rivatives Gate the static-versus-dynamic branch in init_fmap_preproc_wf on FieldmapEstimation.is_dynamic, and align the merges so non-MEDIC estimators keep working alongside MEDIC ones. The derivatives writer dismisses the task entity on dynamic ref/mask sinks and routes the dynamic magnitude reference through the fieldmap suffix.
Stage ds006926 and ds007637 (multi-echo magnitude + phase BOLD) in the cache-test-data job and run the MEDIC end-to-end tests on the veryslow lane. Free runner disk before the data cache is restored, since the added datasets push the root disk past its limit. Skip both datasets in conftest's layout auto-index -- indexing them stalls collection. Add Andrew Van to .zenodo.json.
Matching counts let phase echoes 1/2 through alongside magnitude echoes 1/3, and get_workflow then sorted each part independently by EchoTime, handing warpkit a mismatched pair. Require one phase and one magnitude file per echo entity with matching EchoTime, and order the magnitudes by their paired phase echo.
_unpack_metadata read TotalReadoutTime off the first echo, so inputs carrying only EffectiveEchoSpacing passed the preprocessing timing check and then failed with KeyError. Resolve each echo's readout time with get_trt (honoring use_metadata_estimates and fallback_total_readout_time) and reject echoes that disagree.
…pies A pre-gridded fieldmap was only reoriented, so one on a different lattice was silently sampled as if co-gridded with the EPI. Compare shape and affine against the target and fail clearly on mismatch. unwarp_parallel copied the full coordinate grid for every volume before the semaphore was acquired, so a long series queued one copy per frame. Copy inside the worker once the semaphore is held.
Only the identifier listing was session-filtered, so an identifier reused across sessions pulled every session's files into one estimator. Apply the filter to both lookups; the regex lookup is filtered after the fact since a regex session label would also match as a substring.
init_sdcflows_wf ignored --no-medic and always connected fmap_coeff, which MEDIC does not emit. Forward no_medic to find_estimators and skip the coefficient sink for dynamic estimators, as init_fmap_preproc_wf already does. init_fmap_preproc_wf's outer in_<id> node overrode the raw sources get_workflow set on MEDIC's inputnode with undefined values. Seed it from the estimator for dynamic estimators, whose raw sources need no caller-side preprocessing (PEPOLAR/ANAT keep their current contract).
FieldmapReportlet reduced a 4D fieldmap to one frame but plotted the 4D reference and indexed with the 4D mask, so MEDIC reports failed. Select the same frame from a 4D reference, moving image and mask.
99b7b49 to
0b01326
Compare


Summary
Adds multi-echo dynamic distortion correction (MEDIC) to sdcflows, backed by warpkit. MEDIC estimates a per-volume B0 fieldmap directly from a multi-echo, mag+phase BOLD series, capturing breathing- and motion-driven field changes that a single static fieldmap can't.
Revives #435 / #438 with the simpler pure-Python warpkit (post vanandrew/warpkit#16, no Julia/C++ setup required). Closes #36.
What's new
Workflows
init_medic_wf(sdcflows/workflows/fit/medic.py) — multi-echo phase + magnitude → 4D Hz fieldmap (one volume per timepoint, on the EPI grid), with the first-echo magnitude series asfmap_refand warpkit's per-frame masks asfmap_mask. Two-stage warpkit call (UnwrapPhase→ComputeFieldmap) so the per-frame masks stay accessible. Singlefmapoutput is 4D for MEDIC, leaving the 3D-vs-4D dispatch to the apply consumer.init_dynamic_unwarp_wf(sdcflows/workflows/apply/dynamic.py) — per-volume apply path built onsdcflows.transform.apply_dynamic_unwarp, a per-frame extension of the same scipy/nitransforms-backed resampling that powers the staticinit_unwarp_wf. No warpkit needed at runtime. Includes Jacobian determinant intensity correction (jacobian=Truedefault) sharingtransform.fieldmap_jacobianwith the static path.Interfaces
sdcflows/interfaces/warpkit.py— thinLibraryBaseInterfacewrappers around the two MEDIC stages SDCFlows actually drives:UnwrapPhase(ROMEO) andComputeFieldmap. Lazy import — sdcflows imports warpkit only when these interfaces actually run.Detection / dispatch
EstimatorType.MEDICadded.FieldmapEstimation.__attrs_post_init__detects MEDIC inputs (part-{phase,mag}onbold/epi/sbrefsources), enforces ≥2 echoes with exactly one phase and one magnitude file perechoentity (matchingEchoTime), and rejects partial or mixed part sets.get_workflowinstantiatesinit_medic_wfwithEchoTime-sorted, echo-paired lists (BIDS doesn't guaranteeechoentity == numeric order).part='phase'andpart='mag'queries (some datasets carryIntendedForonly on one side); dedup walks the full sibling set, no reliance on pybids ordering.Plumbing
init_fmap_preproc_wfskipsfmap_coefffor MEDIC (the fieldmap is on the EPI grid by construction, no B-spline rep).init_fmap_derivatives_wfusesMergeSeries(allow_4D=True)so MEDIC's 4Dfmappasses through the sameds_fieldmapsink as the 3D static fmaps.Packaging
warpkitis a core dependency (per review discussion, rather than an extras group). Its non-commercial WUSTL license is documented in theinit_medic_wfmodule docstring; the interfaces import warpkit lazily, only when they run.v3).Validation
echo=Query.REQUIRED),FieldmapEstimationcardinality check (len(phase_files) < 2), and_unpack_metadataruntime guard insideinit_medic_wf.test_apply_dynamic_unwarp_matches_staticpinsapply_dynamic_unwarpto the same Hz→VSM + scipy.ndimage convention as the static_sdc_unwarppath — catches drift in sign / pe_info handling.test_wrangler_filter/test_wrangler_URIsparametrized with a 3-session × 3-echo × {mag,phase} BIDS skeleton.Known compromises
B0FieldIdentifier(or, legacy,IntendedFor) only — same constraint as the existing single-PE EPI branch. Datasets missing both need that metadata added; there is no structure-only opt-in (force_medicwas dropped in review).fmapoutput is 4D for MEDIC. Downstream tools that expect 3D field maps need to either dispatch on dimensionality or block MEDIC-based estimators until they do.Test plan
pytest sdcflows/utils/tests/test_wrangler.py— wrangler MEDIC detection paths (includingno_medic)pytest sdcflows/workflows/fit/tests/test_medic.py—init_medic_wfconstruction +_unpack_metadataguardspytest sdcflows/workflows/apply/tests/test_dynamic.py—init_dynamic_unwarp_wfconstruction + jacobian flag + per-frame resampling vs. static pathpytest -m veryslowwithpip install sdcflows[warpkit]and ds006926 / ds007637 fixtures present — full MEDIC fit + dynamic apply