Jitter removal with moving average

Summary

Implement a moving-average 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. These fluctuations can distort derived quantities such as speed and acceleration.

Providing a built-in smoothing utility lets users reduce this noise consistently before applying analysis methods, without manually manipulating the underlying DataFrame.

Technical Details

• Add the filtering functionality in the preprocessing API.
• Accept a configurable moving-average window size in frames.
• 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.
• Define and document boundary behavior for incomplete windows at the beginning and end of each trajectory.
• Validate the window size and raise an appropriate PedPy custom exception for invalid input.
• 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, boundaries, and invalid window sizes.

Acceptance Criteria

• Users can apply a moving-average filter with a specified positive window size 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) 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 border behavior.
  • Describe in which scenarios the moving average may be used to remove jitter from trajectories.
  • Describe pre-conditions, when the filter may be applied, e.g., windows size vs length of trajectory.

First draft of the potential API:

traj = load_trajectory(foo)


trajectory_smoothed = moving_average(traj=traj, window_size=5, border_behavior=..)
trajectory_smoothed = moving_average(traj, ped_ids=[5, 10], window_size=5, border_behavior=..)