pymovements.events.microsaccades

pymovements.events.microsaccades(velocities: list[list[float]] | list[tuple[float, float]] | np.ndarray, timesteps: list[int] | np.ndarray | None = None, minimum_duration: int = 6, threshold: np.ndarray | tuple[float, float] | str = 'engbert2015', threshold_factor: float = 6, minimum_threshold: float = 1e-10, include_nan: bool = False, name: str = 'saccade') → EventDataFrame

Detect micro-saccades from velocity gaze sequence.

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

The implemetation and its default parameter values are 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:

• velocities (list[list[float]] | list[tuple[float, float]] | np.ndarray) – shape (N, 2) x and y velocities of N samples in chronological order

• timesteps (list[int] | np.ndarray | None) – shape (N, ) Corresponding continuous 1D timestep time series. If None, sample based timesteps are assumed. (default: None)

• minimum_duration (int) –

  Minimum saccade duration. The duration is specified in the units used in timesteps.

  If timesteps is None, then minimum_duration is specified in numbers of samples. (default: 6)

• threshold (np.ndarray | tuple[float, float] | 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_threshold (float) – minimal threshold value. Raises ValueError if calculated threshold is too low. (default: 1e-10)

• include_nan (bool) – Indicator, whether we want to split events on missing/corrupt value (np.nan) (default: False)

• name (str) – Name for detected events in EventDataFrame. (default: ‘saccade’)

Returns:

A dataframe with detected saccades as rows.

Return type:

EventDataFrame

Raises:

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