Jitter removal with Savitzky-Golay filter

[schroedtert]

Summary

Implement a Savitzky-Golay filter to reduce positional jitter in pedestrian trajectories. The filter should smooth each pedestrian's x/y coordinates independently while preserving trajectory metadata and frame alignment.

Background / Context

Trajectory data from recordings and simulations can contain small frame-to-frame position fluctuations. Unlike a simple moving average, a Savitzky-Golay filter fits local polynomials to preserve trajectory curvature and peak shape better while still suppressing noise.

Providing a built-in smoothing utility lets users reduce this noise consistently before computing derived quantities such as speed and acceleration, without manually manipulating the underlying DataFrame.

Technical Details

• Add the filtering functionality in the preprocessing API.
• Use scipy.signal.savgol_filter (or equivalent) as the underlying implementation; add scipy usage in line with the existing scipy~=1.15,<2.0 dependency (no new dependency needed).
• Accept configurable window length (frames) and polynomial order parameters.
• Smooth X_COL and Y_COL independently for each ID_COL, ordered by FRAME_COL.
• Preserve the original pedestrian IDs, frame numbers, and TrajectoryData frame rate.
• Validate that window length is odd, positive, greater than the polynomial order, and does not exceed the number of frames available for a given pedestrian; raise an appropriate PedPy custom exception otherwise.
• Define and document boundary behavior for trajectories shorter than the window length.
• Export the public API from pedpy/__init__.py and add it to __all__ if applicable.
• Add unit tests under tests/unit_tests/ for normal operation, multiple pedestrians, boundary/short trajectories, and invalid parameter combinations.

Acceptance Criteria

• Users can apply a Savitzky-Golay filter with configurable window length and polynomial order to a TrajectoryData instance or the trajectory of a specific pedestrian(s) (by ID)
• Coordinates are smoothed independently per pedestrian and never use samples from another pedestrian
• Output retains all original IDs, frames, non-coordinate columns, and trajectory metadata.
• Boundary behavior is analyzed and implemented & documented:
  • apply filter where possible, remove other data (trajectory may become shorter).
  • adaptive window size at border
  • take inspiration from scipy
  • If window size is larger than trajectory, keep the original trajectory and warn the user
• Use an existing implementation, e.g. scipy
• Invalid window sizes (<=0, even) and invalid polynomial order raise a PedPy custom exception with a useful error message.
• Unit tests cover single- and multi-pedestrian trajectories, boundary frames, and invalid input.
• The new public API is documented.
  • Describe how the window size may be chosen and influence on the result
  • Describe how the polynomial order should be chosen
  • Describe border behavior.
  • Describe in which scenarios the Savitzky-Golay may be used to remove jitter from trajectories.
  • Describe pre-conditions, when the filter may be applied, e.g., window size vs length of trajectory.