pymovements.events.engbert.microsaccades#

pymovements.events.engbert.microsaccades(positions: list[list[float]] | list[tuple[float, float]] | np.ndarray, velocities: list[list[float]] | list[tuple[float, float]] | np.ndarray, threshold: np.ndarray | tuple[float] | str = 'engbert2015', threshold_factor: float = 6, minimum_duration: int = 6, minimum_threshold: float = 1e-10) → pl.DataFrame[source]#

Detect micro-saccades from velocity gaze sequence.

This algorithm has a noise-adaptive velocity threshold parameter, which can also be set explicitly.

The implemetation is based on the description from Engbert & Kliegl [Engbert and Kliegl, 2003] and is adopted from the Microsaccade Toolbox 0.9 originally implemented in R [Engbert et al., 2015].

Parameters:

  • positions (np.ndarray, shape (N, 2)) – x and y positions of N samples in chronological order

  • velocities (np.ndarray, shape (N, 2)) – x and y velocities of N samples in chronological order

  • threshold (np.ndarray, tuple[float, float] or str) – If tuple of floats then use this as explicit elliptic threshold. If str, then use a data-driven velocity threshold method. See compute_threshold() for a reference of valid methods. Default: engbert2015

  • threshold_factor (float) – factor for relative velocity threshold computation. Default: 6

  • minimum_duration (int) – minimal saccade duration in samples. Default: 6

  • minimum_threshold (float) – minimal threshold value. Raises ValueError if calculated threshold is too low. Default: 1e-10

Returns:

A dataframe with detected saccades as rows.

Return type:

pl.DataFrame

Raises:

ValueError – If threshold value is below min_threshold value. If passed threshold is either not two-dimensional or not a supported method.