pymovements.Gaze.resample

Gaze.resample(resampling_rate: float, columns: str | list[str] = 'all', fill_null_strategy: str = 'interpolate_linear') → None

Resample samples to a new sampling rate by timestamps in time column.

samples is resampled by upsampling or downsampling the data to the new sampling rate. Can also be used to achieve a constant sampling rate for inconsistent data.

Parameters:

• resampling_rate (float) – The new sampling rate.

• columns (str | list[str]) – The columns to apply the fill null strategy. Specify a single column name or a list of column names. If ‘all’ is specified, the fill null strategy is applied to all columns. (default: ‘all’)

• fill_null_strategy (str) – The strategy to fill null values of the resampled DataFrame. Supported strategies are: ‘forward’, ‘backward’, ‘interpolate_linear’, ‘interpolate_nearest’. (default: ‘interpolate_linear’)

Examples

Let’s create an example Gaze of 1000Hz with a time column and a position column. Please note that time is always stored in milliseconds in the Gaze.

>>> df = polars.DataFrame({
...     'time': [0, 1, 2, 3, 4],
...     'x': [1, 2, 3, 4, 5],
...     'y': [1, 2, 3, 4, 5],
... })
>>> gaze = Gaze(samples=df, time_column='time', pixel_columns=['x', 'y'])
>>> gaze.samples
shape: (5, 2)
┌──────┬───────────┐
│ time ┆ pixel     │
│ ---  ┆ ---       │
│ i64  ┆ list[i64] │
╞══════╪═══════════╡
│ 0    ┆ [1, 1]    │
│ 1    ┆ [2, 2]    │
│ 2    ┆ [3, 3]    │
│ 3    ┆ [4, 4]    │
│ 4    ┆ [5, 5]    │
└──────┴───────────┘

We can now upsample the Gaze to 2000Hz by interpolating the values in the pixel column.

>>> gaze.resample(
...     resampling_rate=2000,
...     fill_null_strategy='interpolate_linear',
...     columns=['pixel'],
... )
>>> gaze.samples
shape: (9, 2)
┌──────┬────────────┐
│ time ┆ pixel      │
│ ---  ┆ ---        │
│ f64  ┆ list[f64]  │
╞══════╪════════════╡
│ 0.0  ┆ [1.0, 1.0] │
│ 0.5  ┆ [1.5, 1.5] │
│ 1.0  ┆ [2.0, 2.0] │
│ 1.5  ┆ [2.5, 2.5] │
│ 2.0  ┆ [3.0, 3.0] │
│ 2.5  ┆ [3.5, 3.5] │
│ 3.0  ┆ [4.0, 4.0] │
│ 3.5  ┆ [4.5, 4.5] │
│ 4.0  ┆ [5.0, 5.0] │
└──────┴────────────┘

Downsample the Gaze to 500Hz results in the following DataFrame.

>>> gaze.resample(resampling_rate=500)
>>> gaze.samples
shape: (3, 2)
┌──────┬────────────┐
│ time ┆ pixel      │
│ ---  ┆ ---        │
│ i64  ┆ list[f64]  │
╞══════╪════════════╡
│ 0    ┆ [1.0, 1.0] │
│ 2    ┆ [3.0, 3.0] │
│ 4    ┆ [5.0, 5.0] │
└──────┴────────────┘