---
title: "Implemented Methods"
output: rmarkdown::html_vignette
bibliography: methods.bib
vignette: >
  %\VignetteIndexEntry{Implemented Methods}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

The package implements the following methods

* @EngbertKliegl2003
* @Otero-Millan2014
* @NystromHolmqvist2010

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

## @EngbertKliegl2003
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 @EngbertKliegl2003 as
```r
sqrt(median(x^2) - median(x)^2)
```

However, if the value is smaller than [`.Machine$double.eps`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/zMachine.html), it is recomputed via a mean estimator
```r
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 @EngbertKliegl2003.

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 @EngbertKliegl2003. 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-Millan2014
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-Millan2014.

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$.

## @NystromHolmqvist2010

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 @NystromHolmqvist2010.

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