test(motion): pin the centering offset, not just the shape

[daharoni]

Closes #345.

Background

#345 pointed out that the ground-truth motion tests scored only with shift_rmse(..., align=True). align subtracts the per-axis mean residual before the RMSE, which is the correct way to compare two trajectories with different origins, but it means the suite was a pure shape (correlation) check. A regression that stopped centering and let the shifts run off to a large static offset would crop or pad the corrected video needlessly yet still pass.

What's actually happening (not a motion-correction bug)

minisim anchors its ground truth at frame 0 = (0,0) and lets the motion drift from there, so the trajectory generally has a nonzero mean. minian does the opposite: it centers the estimated shifts to zero mean (est_motion_chunk, motions -= motions.mean(axis=0)), specifically to keep the corrected video's bounding box minimal. So the two use different zero points, and the constant gap between them is just the mean of minisim's walk. That is also why the gap scales with motion: a bigger walk has a bigger mean displacement. The slope-1 correlation in the issue confirms registration tracks the motion correctly; only the origin differs.

Verified on the fixture: minian's estimate is essentially zero-mean (|mean(est)| ~0.06-0.15 px) and max|est| stays bounded by the motion range, so nothing is running off.

Change

Two independent tests, per the plan in #345:

• Shape (existing test_estimate_motion_recovers_random_walk): keep align=True, which is the right tool here. Tolerance tightened from 1.0 to 0.25 px (measured aligned RMSE ~0.03 px), so the threshold is no longer ~30x too generous.
• Offset (new test_estimate_motion_offset_is_ground_truth_mean): compute the shift that re-centers the ground truth to zero mean, and require the constant gap between minian's correction and the applied motion to equal it within 0.5 px (measured ~0.06-0.15 px). A runaway offset now fails loudly instead of hiding behind align.

Splitting the two means that if CI ever goes red, it says whether registration drifted (shape) or centering broke (offset).

All 14 tests in test_motion_correction.py pass locally; ruff clean.

🤖 Generated with Claude Code

---

📚 Documentation preview 📚: https://minian--346.org.readthedocs.build/en/346/

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[sneakers-the-rat]

commented in the issue, not exactly how i'd do it because i'm always hunting for stuff to prune, but seems fine