pymovements.Gaze.measure_events_ratio#

Gaze.measure_events_ratio(name: str, time_column: str = 'time', *, sampling_rate: float | None = None, onset_column: str = 'onset', offset_column: str = 'offset') → Expr[source]#

Calculate ratio of time associated with specific events.

This method computes the ratio of time that is associated with events having a specific name. It calculates the ratio from event durations (offset - onset).

If sampling_rate is provided, the ratio is calculated inclusively as:

\[\frac{\sum_{i=1}^{n} (t_{\mathrm{offset},i} - t_{\mathrm{onset},i} + \Delta t)}{t_{\mathrm{max}} - t_{\mathrm{min}} + \Delta t}\]

where \(\Delta t = 1000 / f_s\).

If sampling_rate is not provided, the ratio is calculated as:

\[\frac{\sum_{i=1}^{n} (t_{\mathrm{offset},i} - t_{\mathrm{onset},i})}{t_{\mathrm{max}} - t_{\mathrm{min}}}\]
Parameters:

  • name (str) – Name of events to include in the ratio calculation.

  • time_column (str) – Name of the timestamp column in the samples data. (default: ‘time’)

  • sampling_rate (float | None) – Sampling rate of the gaze data in Hz. If not provided, it will be taken from the experiment if available.

  • onset_column (str) – Name of the column containing event onset times (default: ‘onset’).

  • offset_column (str) – Name of the column containing event offset times (default: ‘offset’).

Returns:

A Polars expression that calculates the event ratio. Use with select(), with_columns(), or group_by().agg() for per-trial ratios.

Return type:

polars.Expr

Examples

>>> import polars
>>> import pymovements as pm
>>> gaze = pm.Gaze(
...     samples=polars.DataFrame({
...         'time': [0, 1, 2, 3],
...         'pixel': [[0, 0], [1, 1], [2, 2], [3, 3]],
...     }),
...     events=pm.Events(
...         name=['blink'],
...         onsets=[1],
...         offsets=[3],
...     ),
... )
>>> gaze.samples.select(gaze.measure_events_ratio('blink'))
shape: (1, 1)
┌───────────────────┐
│ event_ratio_blink │
│ ---               │
│ f64               │
╞═══════════════════╡
│ 0.75              │
└───────────────────┘
Raises:

  • ValueError – If name is not a non-empty string.

  • TypeError – If time_column is not a string.

  • KeyError – If time_column is not present in the samples DataFrame.