events2timeratio#

pymovements.transforms.events2timeratio(events: DataFrame, samples: DataFrame, name: str, time_column: str = 'time', trial_columns: list[str] | None = None, sampling_rate: float | None = None, onset_column: str = 'onset', offset_column: str = 'offset') → Expr[source]#

Create an expression to calculate time-based event ratio.

This function creates an expression that calculates the ratio of time covered by events relative to the total time span.

Parameters:

  • events (pl.DataFrame) – Event data. Must have onset and offset columns.

  • samples (pl.DataFrame) – Sample data containing the time column.

  • name (str) – The name of the event type to calculate ratio for (e.g. ‘blink’).

  • time_column (str) – The name of the column containing timestamps in samples.

  • trial_columns (list[str] | None) – The names of columns identifying trials. If provided, ratios are computed per trial.

  • sampling_rate (float | None) – The sampling rate of the gaze data in Hz. If provided, the ratio is calculated inclusively by adding the sampling interval to the durations and the total time range. If None, the sampling interval is estimated as the mode of the time differences.

  • onset_column (str) – The name of the column containing event onset times.

  • offset_column (str) – The name of the column containing event offset times.

Returns:

An expression that calculates the event ratio. When aggregated with group_by().agg(), computes per-trial ratios.

Return type:

pl.Expr

Examples

>>> import polars as pl
>>> from pymovements.transforms import events2timeratio
>>> events = pl.DataFrame({
...     'name': ['blink', 'blink'],
...     'onset': [1.0, 5.0],
...     'offset': [3.0, 7.0],
... })
>>> samples = pl.DataFrame({'time': [0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0]})
>>> samples.select(events2timeratio(events, samples, 'blink'))
shape: (1, 1)
┌───────────────────┐
│ event_ratio_blink │
│ ---               │
│ f64               │
╞═══════════════════╡
│ 0.75              │
└───────────────────┘
>>> # Inclusive ratio using sampling rate
>>> samples.select(events2timeratio(events, samples, 'blink', sampling_rate=1000.0))
shape: (1, 1)
┌───────────────────┐
│ event_ratio_blink │
│ ---               │
│ f64               │
╞═══════════════════╡
│ 0.75              │
└───────────────────┘