KALMAN FILTER

[HARSHDIPSAHA]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?

The movement library currently provides filtering methods (rolling_filter, savgol_filter) that smooth position data, but they don't leverage the underlying physics of motion or provide direct estimates of velocity and acceleration. For many tracking applications, especially those involving smooth trajectories, we need a filtering method that:

1. Estimates position, velocity, and acceleration directly
2. Accounts for measurement uncertainty in a principled way
3. Can bridge gaps in tracking data by predicting forward based on current motion estimates
4. Provides a more physically-grounded smoothing approach

This PR addresses issue #749.

What does this PR do?

This PR adds a Kalman filter implementation to the movement.filtering module with the following features:

1. New function: kalman_filter() in movement/filtering.py

   • Smoothes position data using a constant acceleration dynamic model
   • Estimates velocity and acceleration directly from position measurements
   • Handles missing data (NaNs) by predicting forward based on current velocity/acceleration estimates
   • Supports configurable noise parameters (process_noise, measurement_noise)
   • Works with movement's xarray DataArray structure (handles dimensions: time, space, keypoints, individuals)
   • Provides flexible output options: position, velocity, acceleration, or all three

2. Implementation details:

   • Constant acceleration dynamic model
   • State vector: [pos_x, pos_y, vel_x, vel_y, acc_x, acc_y] for 2D (or with z for 3D)
   • Supports both 2D and 3D spatial data
   • Automatically infers time step from dataset attributes (fps) or time coordinates
   • Follows movement's patterns: uses @log_to_attrs, supports print_report, etc.

3. Comprehensive tests in tests/test_unit/test_filtering.py:

   • 48 test cases covering various scenarios
   • Tests for position, velocity, acceleration, and "all" outputs
   • Tests with and without NaN values
   • Tests for parameter validation and error handling
   • Tests for different dataset types (poses, bboxes)

4. Example script in examples/kalman_filter.py:

   • Demonstrates basic usage
   • Shows how to get all outputs (position, velocity, acceleration)
   • Includes frequency domain analysis comparison
   • Parameter tuning examples
   • Handling missing data examples

References

• Addresses issue [Feature]: KALMAN FILTER #749

How has this PR been tested?

Unit tests:

• Added comprehensive test suite in tests/test_unit/test_filtering.py::TestKalmanFilter
• 48 test cases covering:
  • Different output types (position, velocity, acceleration, all)
  • Different dataset types (poses, bboxes)
  • Datasets with and without NaN values
  • Parameter validation (invalid output, invalid space dimensions)
  • Time step inference (from fps, from time coordinates, explicit dt)
  • Dimension preservation and coordinate handling

Integration testing:

• Example script (examples/kalman_filter.py) tested and runs successfully
• Verified that the function works with real sample datasets
• Confirmed dimension order preservation and coordinate handling

Backward compatibility:

• No changes to existing filtering functions (rolling_filter, savgol_filter, interpolate_over_time, filter_by_confidence)
• All existing tests still pass
• No breaking changes to the API

Is this a breaking change?

No.

Does this PR require an update to the documentation?

I think yes? To just show the example of using kalman filter.

Example results:

Graph1:

Graph2:

Checklist:

• The code has been tested locally
• Tests have been added to cover all new functionality (48 test cases)
• The documentation has been updated to reflect any changes
• The code has been formatted with [pre-commit]

[sonarqubecloud]

Quality Gate passed

Issues
9 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[HARSHDIPSAHA]

Hi, is there anything I need to add or change for this pr?

[niksirbi]

Hi @HARSHDIPSAHA, thanks for your interest in contributing to movement and sorry for taking this long to respond.

Based on my review, this PR appears to be mostly generated by LLMs, which conflicts with our AI contributions policy. We're closing it for now, but please do get in touch if you think we've got this wrong.

Even setting that aside, we want to be upfront that a Kalman filter implementation is a substantial feature requiring both scientific and code review, and it isn't currently prioritised in our near-term roadmap. It would be difficult for us to commit to a timely and thorough review of a PR of this scope at this stage.

If you'd like to contribute to this in the future, we'd suggest starting a discussion on the existing issue #10 first to agree on scope and design, and then working in small, focused PRs, with full test coverage. That would make the review process much more manageable for everyone.

Thanks for understanding, and we hope to see you contribute in other ways.