Skip to content

FIX: Remove redundant fmap_boldref resample in desc-fmapCoreg_bold.svg report#3640

Merged
effigies merged 2 commits into
nipreps:masterfrom
lobennett:fix/fmap-boldref-double-resample
May 13, 2026
Merged

FIX: Remove redundant fmap_boldref resample in desc-fmapCoreg_bold.svg report#3640
effigies merged 2 commits into
nipreps:masterfrom
lobennett:fix/fmap-boldref-double-resample

Conversation

@lobennett

Copy link
Copy Markdown
Contributor

Closes #3639.

Changes proposed in this pull request

  • Remove the fmap_boldref ApplyTransforms node from init_func_fit_reports_wf.
  • Connect inputnode.fieldmap directly to sdcreg_report.fieldmap.

This restores the wiring that existed before #3387, which is now correct because #3467 rewired func_fit_reports_wf.inputnode.fieldmap to receive boldref_fmap.out_file — a fieldmap already reconstructed onto the BOLD reference grid.

Why

fmap_boldref was added in #3387 to resample a raw RAS fieldmap into BOLD space for the FieldmapReportlet. After #3467 introduced boldref_fmap (a ReconstructFieldmap node) and rewired its output into the reports workflow at fit.py:500, the resample became redundant. Removing fmap_boldref restores correct rendering. Actual SDC is unaffected — unwarp_boldref (fit.py:614) and the time-series resample (apply.py) use ReconstructFieldmap outputs directly. See the linked issue for figures and a centroid trace.

Impact

  • Reports: desc-fmapCoreg_bold.svg now plots the fieldmap at the correct location regardless of BOLD/fmap acquisition geometry.
  • Workflow: one node removed, two connections deleted, one connection added. grep -rn fmap_boldref returns zero matches after the change.
  • Other outputs: none affected. fmap_boldref was reports-only.

Testing

  • Built init_func_fit_reports_wf under sdc_correction=True/False × freesurfer=True/False and walked the workflow graph: fmap_boldref is gone, and sdcreg_report.fieldmap is connected directly from inputnode.fieldmap post-fix; the other three required inputs (reference, moving, mask) remain wired as before.
  • Reproduced the bug on a real subject with fmriprep 25.2.5 (figures in the linked issue) and verified the fix produces correctly-located overlays by invoking FieldmapReportlet with the proposed wiring.
  • ruff check, ruff format --check, and codespell pass on the modified file.

Documentation that should be reviewed

None.

The 'fieldmap' input to init_func_fit_reports_wf is supplied by
boldref_fmap (fit.py:500), which already reconstructs the fieldmap onto
the BOLD reference grid. The fmap_boldref ApplyTransforms node added in
niprepsgh-3387 was correct at the time but became redundant after niprepsgh-3467
rewired the input to come from boldref_fmap.

The redundant resample applies boldref2fmap_xfm (inverted) to data
already in BOLD space, shifting the fieldmap overlay in
desc-fmapCoreg_bold.svg by ||boldref2fmap_xfm||. For acquisitions
where BOLD and fieldmap have similar FOV anchors, the visible shift is
within the brain and the figure looks fine; for acquisitions with
substantially different FOV anchors (e.g. fieldmap reusing functional
prescription with slice thickness/spacing decoupled), the overlay can
render entirely outside the brain.

The actual SDC correction is unaffected: unwarp_boldref (fit.py:614)
and the time-series resample in apply.py both use ReconstructFieldmap
outputs directly without going through fmap_boldref.
@effigies

Copy link
Copy Markdown
Member

Thanks for the detailed analysis and PR! I've triggered the tests. I still need to digest these reports and the referenced PRs, but this is much very much appreciated.

@codecov

codecov Bot commented Apr 25, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 74.24%. Comparing base (acdb0fd) to head (8b7b3ac).
⚠️ Report is 11 commits behind head on master.

Additional details and impacted files
@@            Coverage Diff             @@
##           master    #3640      +/-   ##
==========================================
- Coverage   74.57%   74.24%   -0.33%     
==========================================
  Files          62       62              
  Lines        4975     4954      -21     
  Branches      637      532     -105     
==========================================
- Hits         3710     3678      -32     
- Misses       1131     1144      +13     
+ Partials      134      132       -2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@effigies effigies left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is correct, but a bit disturbing. In general, we've tried to indicate the type and space of the thing being passed between workflows via the name, and it seems that I didn't follow that in #3467, which makes me worry that we aren't being consistent elsewhere.

I've updated the deeply outdated docstring so at least the space is documented here.

cc @mgxd as a heads up.

@effigies effigies merged commit 3f9f398 into nipreps:master May 13, 2026
20 of 23 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Fieldmap overlay in desc-fmapCoreg_bold.svg is resampled twice, may render outside the brain

2 participants