Skip to content

rtsdiff circular: choose the 2π branch from the previous posterior (fixes #240) - #241

Merged
florisvb merged 1 commit into
masterfrom
fix-240-circular-branch
Oct 27, 2026
Merged

florisvb merged 1 commit into
masterfrom
fix-240-circular-branch

Conversation

@florisvb

Copy link
Copy Markdown
Owner

Fixes #240.

Problem

With circular=True, rtsdiff wrapped each innovation against the filter's prediction. After a large one-step change in angle (still < π), a high-gain filter's next prediction can overshoot the measurement by more than π. The wrapped innovation then takes the branch 2π away, and the filter locks onto an aliased solution whose derivative is off by, or keeps growing by, multiples of 2π/dt. Raising order doesn't help: at the gains optimize picks (log_qr_ratio 12–14), order 2 aliases from smaller steps than order 1.

Change

  • kalman_filter(..., circular=False): when True, the innovation stays wrapped, but its branch is chosen relative to the previous posterior, r = C x̂ₙ₋₁|ₙ₋₁: r + wrap(y − r) − C x̂ₙ|ₙ₋₁. Across missing data, r follows the model's prediction. innovation_fn keeps its signature, so this is backward compatible; combining the two raises ValueError.
  • rtsdiff(..., circular_branch='posterior'): the new rule is the default. 'prediction' keeps the previous behaviour exactly, which is still the better choice for fast, steady rotation through noise at low gain. Both docstrings explain the trade-off.

How the option was chosen

Prototyped against the current behaviour, a "fold the predicted increment into [−π, π]" variant, np.unwrap + plain filter, the wrapped Kalman filter of Traa & Smaragdis (2013), and an innovation gate. Branching from the previous posterior was the only option with no aliasing in the step sweep (orders 1–3, log_qr_ratio 2–14) or on the Drosophila trajectory from the issue. On that trajectory with added noise at log_qr_ratio 12 it had no wrong-branch failures up to σ = 0.2 rad (out of 100 seeds), versus 70–100% for the current method. Its cost: on fast noisy rotation at low gain it lags, which is why 'prediction' stays available.

Tests

New tests in test_diff_methods.py. The 11 #240 regression tests below fail with the old prediction-branch default:

  • single steps < π at the issue's settings, with and without forwardbackward (8 cases)
  • the issue's Drosophila trajectory compared with differentiating np.unwrapped data (2 cases)
  • noise robustness on that trajectory at σ = 0.2 over 20 seeds, against the filter run as if the wrapping were known

These also pass under both branches:

  • equivalence with the plain filter on unwrapped data for uniform steps, irregular steps, NaN gaps, and 2D input along axis=1
  • invariance to adding whole turns to individual samples (both branches)
  • argument validation
  • the existing test_circular_rtsdiff, now run for both branches

Checks

  • coverage run --source=pynumdiff -m pytest -s: 234 passed; kalman_smooth.py at 99%. The 2 missed lines are an existing convex_smooth error branch.
  • pylint pynumdiff: 9.39 (9.37 before).
  • Sphinx build: the new parameters render; no new warnings.
  • Notebook 7's data gives identical results under both branches, so its saved outputs are unchanged.

🤖 Generated with Claude Code

…240)

With circular=True the innovation was wrapped against the filter's prediction. After a large one-step
change in angle, a high-gain prediction can overshoot the measurement by more than pi, so the wrapped
innovation takes the branch 2pi away and the filter locks onto an aliased solution whose derivative is
off by, or grows by, multiples of 2pi/dt.

kalman_filter gains circular=True, which keeps the wrapped innovation but picks its branch relative to
the previous posterior: r + wrap(y - r) - pred. rtsdiff uses it by default and keeps the old behaviour
as circular_branch='prediction', which still tracks fast, steady rotation through noise better at low
gain. innovation_fn is unchanged, so this is backward compatible.

Tests cover the issue's step and Drosophila examples, noise robustness at the issue's gain, equivalence
with differentiating unwrapped data (irregular steps, NaNs, multidim), invariance to whole turns, and
argument validation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@florisvb

Copy link
Copy Markdown
Owner Author

Verified that this fix works on a much larger dataset on a downstream repo, as well.

@florisvb
florisvb merged commit f4184e3 into master Oct 27, 2026
2 checks passed
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.

rtsdiff(circular=True) can runaway on an aliased solution

1 participant