pymovements.Gaze.nullify_event_samples#

Gaze.nullify_event_samples(name: str, *, padding: float | tuple[float, float] = (25, 25)) → None[source]#

Set gaze sample values to null during detected events.

This method nullifies gaze data columns (e.g. pixel, position, velocity, acceleration) for all samples that fall within the time intervals of detected events of the specified type. This is useful for removing artifact data during events such as blinks, where gaze samples are unreliable.

Parameters:

  • name (str) – The name of the event type whose samples should be set to null (e.g. 'blink'). Must match an event name in events.

  • padding (float | tuple[float, float]) – Padding to extend each event interval, in the same units as the time column. If a single float, the same padding is applied symmetrically before and after each event. If a tuple (before, after), before is subtracted from the onset and after is added to the offset. Both values must be non-negative. Default is (25, 25).

Raises:

Examples

>>> import polars
>>> import pymovements as pm
>>>
>>> gaze = pm.Gaze(
...     samples=polars.DataFrame({
...         'time': polars.Series(range(6), dtype=polars.Int64),
...         'pixel': [[1.0, 2.0]] * 6,
...     }),
...     events=pm.Events(name='blink', onsets=[2], offsets=[3]),
... )
>>> gaze.nullify_event_samples('blink', padding=0)
>>> gaze.samples['pixel'].to_list()
[[1.0, 2.0], [1.0, 2.0], None, None, [1.0, 2.0], [1.0, 2.0]]