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#
Fixation identification based on dispersion threshold (I-DT).
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 (list[list[float]] | list[tuple[float, float]] | np.ndarray) – shape (N, 2) Continuous 2D position time series
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 fixation duration. The duration is specified in the units used in
timesteps. Iftimestepsis None, thenminimum_durationis specified in numbers of samples. (default: 100)dispersion_threshold (float) – Threshold for dispersion for a group of consecutive samples to be identified as fixation. (default: 1.0)
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: ‘fixation’)
- Returns:
A dataframe with detected fixations as rows.
- Return type:
- Raises:
TypeError – If minimum_duration is not of type
intor timestepsValueError – If positions is not shaped (N, 2) If dispersion_threshold is not greater than 0 If duration_threshold is not greater than 0