pymovements
pymovements copied to clipboard
feature: add resample() transformation function
Description
The resample transformation function offers multiple ways to adjust the sampling rate of gaze data. This function enables the adjustment of temporal frequency through both upsampling and downsampling. Additionally, it enables achieving a constant sampling rate for gaze data with inconsistent timestamps.
Resampling can be applied to both GazeDataFrame
and entire Dataset
. By default, it interpolates all columns of the resampled data frame. When applied to a GazeDataFrame
containing multiple trials, the function resamples the data frame grouped by trial_columns
. We exclude trial_columns
from the interpolation in transforms.resample
, as interpolation is not applicable to these columns. After processing, we fill the trial_columns
.
The new sampling rate determined by the resampling process is stored in the Experiment
object of the GazeDataFrame
.
The resampling function processes timestamps with microsecond precision, supporting only sampling rates that divide 1,000,000.
Supported strategies for filling column values in newly created rows through resampling include forward filling, backward filling, linear interpolation, and nearest value interpolation.
Fixes issue #689.
Implemented changes
- [x] Implement
transforms.resample
function - [x] Add
transforms._apply_on_columns
helper function, applying a function on nested and normal columns of apl.DataFrame
- [x] Add logic handling resampling call in
GazeDataFrame.apply
- [x] Add
GazeDataFrame.resample
with examples in docs - [x] Add
Dataset.resample
Type of change
- [x] New feature (non-breaking change which adds functionality)
How Has This Been Tested?
- [x] Add resampling step in functional tests of processing gaze files and datasets.
- [x] Add unit tests in
tests/unit/gaze/transforms/resample_test.py
, testing for expected return values and exceptions - [x] Test resampling of
GazeDataFrame
withtest_gaze_dataframe_resample_expected
inunit.gaze.gaze_transform_test
- [x] Test if assigning new sampling rate to Experiment in GazeDataFrame after resampling in
test_gaze_dataframe_resample_changes_experiemnt_sampling_rate
ofunit.gaze.gaze_transform_test