pymovements.events.ivt#
- pymovements.events.ivt(velocities: list[list[float]] | list[tuple[float, float]] | np.ndarray, timesteps: list[int] | np.ndarray | None = None, minimum_duration: int = 100, velocity_threshold: float = 20.0, include_nan: bool = False, name: str = 'fixation') EventDataFrame#
Identification of fixations based on velocity-threshold (I-VT).
The algorithm classifies each point as a fixation if the velocity is below the given velocity threshold. Consecutive fixation points are merged into one fixation.
The implementation and its default parameter values are based on the description and pseudocode from Salvucci and Goldberg [Salvucci and Goldberg, 2000].
- Parameters:
velocities (list[list[float]] | list[tuple[float, float]] | np.ndarray) – shape (N, 2) Corresponding continuous 2D velocity 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)velocity_threshold (float) – Threshold for a point to be classified as a fixation. If the velocity is below the threshold, the point is classified as a fixation. (default: 20.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:
ValueError – If velocities is None If velocities does not have shape (N, 2) If velocity threshold is None. If velocity threshold is not greater than 0.