pymovements.events.idt#

pymovements.events.idt(positions: list[list[float]] | list[tuple[float, float]] | np.ndarray, timesteps: list[int] | np.ndarray | None = None, minimum_duration: int = 100, dispersion_threshold: float = 1.0, include_nan: bool = False, name: str = 'fixation') → EventDataFrame[source]#

Fixation identification based on dispersion threshold.

The algorithm identifies fixations by grouping consecutive points within a maximum separation (dispersion) threshold and a minimum duration threshold. The algorithm uses a moving window to check the dispersion of the points in the window. If the dispersion is below the threshold, the window represents a fixation, and the window is expanded until the dispersion is above threshold.

The implementation and its default parameter values are based on the description and pseudocode from Salvucci and Goldberg [Salvucci and Goldberg, 2000].

Parameters:

  • positions (array-like, shape (N, 2)) – Continuous 2D position time series

  • timesteps (array-like, shape (N, )) – Corresponding continuous 1D timestep time series. If None, sample based timesteps are assumed.

  • minimum_duration (int) –

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

    If timesteps is None, then minimum_duration is specified in numbers of samples.

  • dispersion_threshold (float) – Threshold for dispersion for a group of consecutive samples to be identified as fixation

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

  • name – Name for detected events in EventDataFrame.

Returns:

A dataframe with detected fixations as rows.

Return type:

pl.DataFrame

Raises:

  • TypeError – If minimum_duration is not of type int or timesteps

  • ValueError – If positions is not shaped (N, 2) If dispersion_threshold is not greater than 0 If duration_threshold is not greater than 0