extract_saccades {saccadr} | R Documentation |
Extract saccades from samples using votes from selected methods.
Description
Extract saccades from samples using votes from selected methods. Each method votes whether
a given sample belongs to a saccade. Next, saccades are identified via a majority vote using the
vote_threshold
parameter, as well as a minimum duration and minimal temporal separation criteria.
Please note that units of the gaze samples must be in degrees of visual angle. The units are important
as some methods use specific (e.g., physiologically plausible) velocity and acceleration thresholds.
By default, ensemble includes methods proposed by Engbert & Kliegl (2003) ("ek"
),
Otero-Millan et al. ("om"
), and Nyström & Holmqvist (2010) ("nh"
),
see Implemented Methods vignette. However, it can be extended
via custom methods, see Using Custom Methods vignette.
By default, the function returns a table with identified saccades but can return a matrix with methods' votes
per sample instead (return_votes = TRUE
).
Usage
extract_saccades(
x,
y,
sample_rate,
trial = NULL,
methods = list(method_ek, method_om, method_nh),
velocity_function = saccadr::diff_ek,
options = NULL,
binocular = "merge",
vote_threshold = ifelse(length(methods) == 1, 1, (length(methods) - 1)),
minimal_duration_ms = 12,
minimal_separation_ms = 12,
return_votes = FALSE
)
Arguments
x |
Horizontal coordinate, either a vector for monocular data or a two-column matrix for binocular data. |
y |
Vertical coordinate, either a vector for monocular data or a two-column matrix for binocular data. |
sample_rate |
Sampling rate in Hz. It is assumed to be common for the entire time series. If the time series contains chunks (trials) that were recorded using different acquisition rate (e.g., SR Research Eyelink allows to set different acquisition rate for each recording / trial), you would need to split the time series and analyze them separately. |
trial |
Optional vector with trial ID. If omitted, all samples are assumed to belong to a single trial. Velocity, acceleration, and saccades themselves are computed respecting trial borders. |
methods |
A list with saccade detection methods, can include external functions that
implement sample classification (see Using Custom Methods vignette). Package methods include
Engbert & Kliegl (2003) ( |
velocity_function |
A handle to a function to compute velocity and acceleration. Defaults to a method
suggested by Engbert & Kliegl (2003) |
options |
A named list with options for saccade detection (see |
binocular |
Specifies how a binocular data is treated. Options are |
vote_threshold |
Value between 1 and N (where N is number of used methods) defining a vote threshold for a
saccade. By default, all but one method |
minimal_duration_ms |
Minimal duration of a saccade in milliseconds. Shorter candidate saccades are discarded, |
minimal_separation_ms |
Minimal time separation between saccades in milliseconds. Saccades that are separated by a shorter interval of "not a saccade" votes, will be merged including that period. |
return_votes |
Logical. Whether function should return extracted microsaccades ( |
Details
Variables that describe saccade
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.
Value
A data.frame
with saccade properties (see details), if return_votes = FALSE
.
Alternatively, it returns votes per sample (return_votes = TRUE
). For a monocular processing (monocular
input, cyclopean or merged binocular data) it is a matrix with nrow(x)
rows and length(methods)
columns with 0/1 votes for each sample and method. For binocular processing, function returns a two element list
with
the similar matrices but per eye.
See Also
method_ek
, method_om
, method_nh
, diff_ek
, diff_nh
Examples
# Single trial
data(single_trial)
saccades <- extract_saccades(single_trial$x, single_trial$y, 500)
# Multiple trials
data(monocular_ten_trials)
saccades <- extract_saccades(monocular_ten_trials$x,
monocular_ten_trials$y,
500,
trial = monocular_ten_trials$trial)
# binocular saccades
data("single_trial_binocular")
saccades_b <- saccadr::extract_saccades(single_trial_binocular[, c('xL', 'xR')],
single_trial_binocular[, c('yL', 'yR')],
sample_rate = 1000)
# cyclopean saccades from binocular data
saccades_c <- saccadr::extract_saccades(single_trial_binocular[, c('xL', 'xR')],
single_trial_binocular[, c('yL', 'yR')],
sample_rate = 1000,
binocular = "cyclopean")
# monocular saccades from binocular data
saccades_m <- saccadr::extract_saccades(single_trial_binocular[, c('xL', 'xR')],
single_trial_binocular[, c('yL', 'yR')],
sample_rate = 1000,
binocular = "monocular")
# Using a single method
saccades <- extract_saccades(single_trial$x, single_trial$y, 500, methods = method_om)
# Using two methods
saccades <- extract_saccades(single_trial$x,
single_trial$y,
500,
methods = list(method_ek, method_om))
# Alternative velocity computation method
saccades <- extract_saccades(single_trial$x, single_trial$y, 500, velocity_function = diff_nh)
# A strict unanimous decision threshold
saccades <- extract_saccades(single_trial$x, single_trial$y, 500, vote_threshold = 3)
# A slacker criterion that at least one of the three methods must label sample as a saccade
saccades <- extract_saccades(single_trial$x, single_trial$y, 500, vote_threshold = 1)
# Only longish saccades are extracted
saccades <- extract_saccades(single_trial$x, single_trial$y, 500, minimal_duration_ms = 20)