📝 Add a theory note on phase offset ambiguities - #33
Merged
Conversation
Derives what the unknown turn count left by spatial unwrapping does to the MCPC-3D-S offset estimate, why resolving it per frame is unstable when the bulk field approaches the half-wrap, and how a mismatched offset/field pair becomes detectable. Documents the two-stage selector MEDIC uses and the requirements on the field estimator. Theory only; no measured results.
- Replace the appendix's "plot phase against echo time" prose with a drawn figure of the candidate pencil, and state the pivot at TE0 as a consequence of the proof rather than something the reader must picture. - Add section 8.1 giving what the unwrapper, the two masks, and the weighted median must provide, as properties rather than settings, so the spec is self-contained without describing any particular implementation. - Correct the delta = 0 guard: an exact float comparison never fires, so specify a tolerance test. - Drop the even-sized-median qualification, which was opaque and whose closing claim about the detector was wrong (for k near 0.58-0.74 it accepts a single wrong candidate rather than rejecting all of them). - Remove the test-fixture reference and its two mistranscribed voxel counts so the note stands on its own. - Add a units statement, sharpen the second unwrap's description, condense the recap that restated sections 6 and 7, and shorten the reference-data block. - Layout: let the appendix flow instead of forcing a pagebreak, and keep the reference-data box unbreakable; 11 pages down to 10.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #33 +/- ##
=======================================
Coverage 96.25% 96.25%
=======================================
Files 18 18
Lines 1280 1280
=======================================
Hits 1232 1232
Misses 48 48 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
Adds a standalone Typst theory note to the notes/ area documenting (at an implementation-agnostic level) the integer ambiguity in phase-offset estimation for evenly spaced multi-echo field mapping, why ROMEO’s per-frame “smallest-field” choice can tip near the half-wrap, and the intercept-based procedure used to detect/repair tipped frames.
Changes:
- Introduces a new Typst note describing the signal model, candidate ladder ambiguity (Prop. 1), and failure mode near the half-wrap.
- Specifies the intercept-based detection/selection algorithm (Prop. 2) and the required properties of the unwrapper/masks/weighted median.
- Commits the compiled PDF alongside the Typst source.
Reviewed changes
Copilot reviewed 1 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| notes/phase-offset-ambiguities.typ | New Typst source for the phase-offset ambiguity theory note, including propositions and an algorithm/spec section. |
| notes/phase-offset-ambiguities.pdf | Compiled PDF output of the note committed alongside the source. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a standalone theory note (
notes/phase-offset-ambiguities.typ, with thecompiled PDF) covering the phase-offset ambiguity in multi-echo field mapping:
why the MCPC-3D-S offset estimate leaves one integer undetermined, why ROMEO's
global correction tips on individual frames for subjects whose field sits near
the half-wrap, and the intercept-based procedure that detects and repairs it.
Contents
spaced echoes every candidate predicts identical recorded phase — so no
statistic over the phase can rank them and a prior is unavoidable.
intercept signature that a mismatched offset/field pair leaves behind.
the estimator of the global field has to be robust against.
Notes for reviewers
to a license-friendly reimplementation. Section 8.1 states what the unwrapper,
the two masks, and the weighted median must provide — as properties, not as
settings — rather than transcribing any particular implementation. There are
deliberately no unwrapper flags, mask recipes, or references to this repo's
test fixtures.
ds006131v2.0.1. The dataset name, version, subjectcount, echo times (5 echoes, TE0 = 14.2 ms, uniform 24.73 ms spacing) and
243-frame length were checked against OpenNeuro; the uniform spacing matters
because Prop. 1 depends on it.
half-wrap 20.22 Hz, wrap 40.44 Hz, k = 0.574.
reconstruction is out of scope and not described.
CI
Docs only — no Python or C++ changes, so nothing touching the wheel matrix,
pybind11 ABI, or ITK. The PDF is committed next to the source; rebuild with
typst compile notes/phase-offset-ambiguities.typ.