# Implemented Methods

The package implements the following methods

- Engbert and Kliegl (2003)
- Otero-Millan et al. (2014)
- Nyström and Holmqvist (2010)

Each method has additional parameters that can be passed via the `options` argument of the `extract_saccades()` function.

## Engbert and Kliegl (2003)

The algorithm labels a sample as a saccade if velocity, measured in units of its standard deviation (see below), exceeds a predefined threshold (defaults to \(6\)) and the duration of a super-threshold period exceeds a minimal duration (defaults to \(12\) milliseconds). This method makes no assumptions about velocity in the units of degrees per second and can be used on any data (e.g., where samples encode gaze in screen position units).

The standard deviation is computed following formula #2 in Engbert and Kliegl (2003) as

    sqrt(median(x^2) - median(x)^2)

However, if the value is smaller than `.Machine$double.eps`, it is recomputed via a mean estimator

    sqrt(mean(x^2) - mean(x)^2)

Only a monocular version of the algorithm is implemented with binocular saccades computed using overlapping votes from two eyes. For method details and rationale for default parameter values refer to Engbert and Kliegl (2003).

Parameters:

- `ek_velocity_threshold` Velocity threshold for saccade detection in standard deviations. Defaults to \(6\).
- `ek_sd_fun` Function used to compute standard deviation for velocities. Defaults to `sd_via_median_estimator()` that implements formula #2 in Engbert and Kliegl (2003). Can be replaced with `sd()`, `mad()`, or a custom function.
- `ek_minimal_duration_ms` Minimal duration of a saccade in milliseconds. Defaults to \(12\).
- `ek_minimal_separation_ms` A minimal required time gap between saccades. Defaults to \(12\).

## Otero-Millan et al. (2014)

The algorithm:

1. Detect local velocity peaks.
2. Filter them based on a minimal inter-peak interval (defaults to \(30\) ms) and maximal allowed saccade rate (defaults to \(5\) Hz).
3. Identify the onset and offset of a potential saccade using an absolute velocity threshold in degrees per second (defaults to \(3\)).
4. Compute peak velocity and peak acceleration before and after the peak velocity was reached.
5. Rotate velocity and peak acceleration via PCA and retain components above a predefined threshold for explained variance (defaults to \(0.05\)).
6. Perform a cluster analysis on the remaining components for \(2\), \(3\), and \(4\) picking the solution with the smallest silhouette.
7. Saccades are identified as a cluster with the highest average peak velocity.

For method details and rationale for default parameter values refer to Otero-Millan et al. (2014).

Parameters:

- `om_minimal_inter_peak_time_ms` Minimal inter-peak interval in milliseconds. Defaults to \(30\)
- `om_maximal_peaks_per_second` Maximal allowed number of peaks per second. Defaults to \(5\).
- `om_velocity_threshold_deg_per_sec` Threshold saccade velocity in °/s. Defaults to \(3\).
- `om_pca_variance_threshold` Minimal variance explained by retained rotated components. Defaults to \(0.05\).

## Nyström and Holmqvist (2010)

The algorithm:

1. Identify physiologically implausible velocity and acceleration peaks (defaults to \(1000 \deg/s\) and \(100000 \deg/s^2\)).
2. Identify noise onset/offset as samples around the implausible velocity/acceleration that are above median velocity. Exclude these samples from analysis.
3. Identify velocity threshold \(PT = mean(V_{subthreshold}) + 6 \cdot std(V_{subthreshold})\) via an iterative method starting at arbitrary \(PT\) value (defaults to \(100 \deg/s\)). Stop when threshold change is below \(1 \deg/s\).
4. Identify saccades as periods with peaks peaks above threshold \(PT\) and adjacent samples that are above \(PT_{onset/offset} = mean(V_{subthreshold}) + 3 \cdot std(V_{subthreshold})\).

For method details and rationale for default parameter values refer to Nyström and Holmqvist (2010).

Parameters:

- `nh_max_velocity` Maximal physiologically plausible velocity in °/s. Defaults to `1000`.
- `nh_max_acceleration` Maximal physiologically plausible acceleration in °/s². Defaults to `100000`.
- `nh_initial_velocity_threshold` Initial velocity threshold in °/s. Defaults to `100`.

## References

Engbert, Ralf, and Reinhold Kliegl. 2003. “Microsaccades uncover the orientation of covert attention.” Vision Research 43 (9): 1035–45. https://doi.org/10.1016/S0042-6989(03)00084-1.
Nyström, Marcus, and Kenneth Holmqvist. 2010. “An adaptive algorithm for fixation, saccade, and glissade detection in eyetracking data.” Behavior Research Methods 42 (1): 188–204. https://doi.org/10.3758/BRM.42.1.188.
Otero-Millan, J., Jose L Alba Castro, Stephen L Macknik, and S. Martinez-Conde. 2014. “Unsupervised clustering method to detect microsaccades.” Journal of Vision 14 (2): 18–18. https://doi.org/10.1167/14.2.18.