Skip to content

Fix dual-echo denoising regression and chapter text - #100

Merged
tsalo merged 1 commit into
mainfrom
fix-dual-echo-denoising
Nov 14, 2026
Merged

tsalo merged 1 commit into
mainfrom
fix-dual-echo-denoising

Conversation

@tsalo

@tsalo tsalo commented Nov 14, 2026

Copy link
Copy Markdown
Member

Summary

Fixes correctness problems in the Dual-Echo Denoising chapter and the regress_one_image_out_of_another helper.

Code (content/book_utils.py)

  • The regression direction was reversed. lstsq fit the short echo using the later echo. It now fits the short echo (nuisance) to the later echo (data), as in Bright & Murphy (2013).
  • The per-voxel betas were overwritten. betas = ... replaced the array with a scalar on every loop pass, so the last voxel's beta was applied to every voxel. The fit is now vectorized, with one beta per voxel, and guards voxels with zero nuisance variance.
  • Dropped the unnecessary intercept column (both series are already mean-centered) and added a docstring.

Chapter (content/04_Dual_Echo_Denoising.md)

  • The carpet plot titles were swapped (echo 2 was labeled "First Echo"). They are now titled with each echo time, read from the JSON sidecars, and the BAD/GOOD/GREAT labels are replaced with neutral ones.
  • Clarified the theory: fractional BOLD change grows roughly in proportion to TE, while S0 fluctuations (motion, inflow) affect all echoes. Also noted that the regression is voxelwise and removes a small amount of true BOLD signal.
  • Softened the "no real cost" claim: a very short echo fits into dead time with spiral-out readouts, but standard EPI needs partial Fourier or acceleration and may lengthen the minimum TR.
  • Added a warning that the tutorial dataset's first echo is 14.2 ms, not a true short echo, so the example demonstrates the procedure only.

Other

  • Acquiring_Multi_Echo_Data.md: "~5ms" is now "a few milliseconds", consistent with the chapter.

Testing

  • Synthetic data with known voxelwise betas: the denoised output matches the planted signal up to the expected fitting noise, and voxel means are preserved.
  • Tutorial data: the output contains only finite values, and the median voxel SD drops from 262.7 to 236.9.
  • make book succeeds locally; only this chapter re-executed.

Note: CI renders from the published execution cache, so make publish-cache must be run before the deployed site picks up the new outputs.

🤖 Generated with Claude Code

- Fit the short echo to the later echo (the regression direction was
  reversed) and keep one beta per voxel (the loop overwrote a scalar,
  so the last voxel's beta was applied to the whole brain).
- Correct the swapped carpet plot labels and title them with echo times.
- Clarify the BOLD/TE relationship, acquisition trade-offs, and that the
  tutorial data's first echo (14.2 ms) is not a true short echo.
@tsalo
tsalo merged commit 482dc76 into main Nov 14, 2026
2 checks passed
@tsalo
tsalo deleted the fix-dual-echo-denoising branch November 14, 2026 19:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant