saccadr is a modular and extendable R package to extract (micro)saccades from gaze samples via an ensemble of methods approach.

Although there is an agreement about a general definition of a saccade, the more specific details are harder to agree upon. Therefore, there are numerous algorithms that extract saccades based on various heuristics, which differ in the assumptions about velocity, acceleration, etc. The package uses these methods to label individual samples and then applies a majority vote approach to identify saccades. The package includes three methods (see Implemented Methods vignette) but can be extended via custom methods (see Using custom methods vignette). It also uses a modular approach to compute velocity and acceleration from noisy samples (see Velocity computation vignette). Finally, you can obtain methods votes per gaze sample instead of saccades (see Using sample votes vignette).

The extract_saccades() function uses several methods to label individual samples as belonging to a saccade, classifies a sample as a potential saccade if its proportion of votes exceeds a preset threshold, and then identifies saccades based on minimal saccade duration and minimal time between the saccades. For binocular data, 1) samples can be averaged before velocity computation, 2) votes can be merged so that function returns binocular saccades, or 3) saccades are extracted for each eye separately.

Currently, the library implements saccade detection using on the following saccade detection methods. When using this package, please cite both the package and individual methods.

• method_ek : Engbert, R., & Kliegl, R. (2003). Microsaccades uncover the orientation of covert attention. Vision Research, 43(9), 1035–1045. https://doi.org/10.1016/S0042-6989(03)00084-1
• method_om : Otero-Millan, J., Castro, J. L. A., Macknik, S. L., & Martinez-Conde, S. (2014). Unsupervised clustering method to detect microsaccades. Journal of Vision, 14(2), 18–18. https://doi.org/10.1167/14.2.18
• method_nh : Nyström, M., & Holmqvist, K. (2010). An adaptive algorithm for fixation, saccade, and glissade detection in eye tracking data. Behavior Research Methods, 42(1), 188–204. https://doi.org/10.3758/BRM.42.1.188

## Installation

For current stable version use

install.packages("saccadr")

To install the development version from github

library("devtools")
install_github("alexander-pastukhov/saccadr", dependencies=TRUE)

## Usage

The main function is extract_saccades(). Minimally, it takes x and y gaze samples, and sampling rate returning a table with extracted saccades. Note that the function expects that units of the gaze samples are degrees of visual angle, as some methods use physiologically plausible velocity and acceleration thresholds.

data("single_trial")
saccades <- extract_saccades(single_trial$x, single_trial$y, sample_rate = 500)

### Multiple trials

When the recording spans multiple trials, you need to specify this via trial parameter. This way velocity computation and saccade detection methods respect trial boundaries.

data(monocular_ten_trials)
saccades <- extract_saccades(monocular_ten_trials$x monocular_ten_trials$y,
500,

## Return values

The extract_saccades() function returns a table with following columns:

• Trial Trial index.
• Eye “Monocular” for monocular inputs. “Cyclopean” for binocular data that was averaged before applying algorithms. “Binocular” for binocular data with votes averaged after applying algorithms. “Left” or “Right” for binocular data when eyes are processed independently.
• OnsetSample Index of the first sample.
• OffsetSample Index of the last sample.
• Onset Onset time relative to the trial start in milliseconds.
• Offset Offset time relative to the trial start in milliseconds.
• Duration Duration in milliseconds.
• DisplacementX Horizontal displacement measured from the first to the last sample.
• DisplacementY Vertical displacement measured from the first to the last sample.
• Displacement Displacement magnitude measured from the first to the last sample.
• DisplacementPhi Displacement direction measured from the first to the last sample.
• AmplitudeX Horizontal displacement measured from the leftmost to the rightmost sample.
• AmplitudeY Vertical displacement measured from the lowest to the uppermost sample.
• Amplitude Displacement magnitude measured from the most extreme samples.
• AmplitudePhi Displacement direction measured from the most extreme samples.
• VelocityPeak Peak velocity.
• VelocityAvg Average velocity.
• AccelerationPeak Peak acceleration.
• AccelerationAvg Average acceleration.
• AccelerationStart Peak acceleration before peak velocity was reached.
• AccelerationStop Peak acceleration after peak velocity was reached.

Alternatively, if you use parameter return_votes = TRUE the function can return votes per sample and method (and eye, for binocular data). Please see Using sample votes vignette for details.