ivt_filter: I-VT algorithm for fixation and saccade detection

In kollaR: Filtering, Visualization and Analysis of Eye Tracking Data

I-VT algorithm for fixation and saccade detection

Description

Apply an I-VT filter to the eye tracking data. The algorithm identifies saccades as periods with sample-to-sample velocity above a threshold and fixations as periods between saccades. See Salvucci and Goldberg 2000. Identifying fixations and saccades in eye tracking protocols. Proc. 2000 symposium on Eye tracking research and applications for a description.

Input data must be a data frame with the variables timestamp, x.raw and y.raw as variables. Other variables can be included but will be ignored. This function does not perform pre-processing in the form of interpolation or smoothing. Use the function process.gaze for this. Timestamps are assumed to be in milliseconds. Default settings assume that x and y coordinates are in pixels. The output data is a list with three data frames: fixations includes all detected fixations with coordinates, duration and a number of other metrics, saccades includes data for saccades, filt.gaze is a sample-by-sample data frame with time stamps, raw and filtered gaze coordinates for fixations. The function has a number of parameters for removing potentially invalid fixations and saccades. The parameter min.fixation.duration can be used to remove unlikely short fixations. If the parameter missing.samples threshold is set to a value lower than 1, fixations with a higher proportion of missing raw samples are removed.

Usage

ivt_filter(
  gaze_raw,
  velocity.filter.ms = 20,
  velocity.threshold = 35,
  min.saccade.duration = 10,
  min.fixation.duration = 40,
  one_degree = 40,
  save.velocity.profiles = FALSE,
  xcol = "x.raw",
  ycol = "y.raw",
  distance.threshold = 0.7,
  merge.ms.threshold = 75,
  missing.samples.threshold = 0.5
)

Arguments

gaze_raw	Data frame with unfiltered gaze data. Include the variable timestamp with timing in ms and columns with raw x and y data as specified by the parameters xcol and ycol or their default values
velocity.filter.ms	Window in milliseconds for moving average window used for smoothing the sample to sample velocity vector.
velocity.threshold	Velocity threshold for saccade detection in degrees/second
min.saccade.duration	Minimum duration of saccades in milliseconds
min.fixation.duration	Minimum duration of fixations in milliseconds
one_degree	One degree of the visual field in the unit of the raw x and y coordinates, typically pixels
save.velocity.profiles	If TRUE, return velocity profiles of each detected saccade as a variable in the saccades data frame
xcol	Name of the column where raw x values are stored. Default: x.raw
ycol	Name of the column where raw y values are stored. Default: y.raw
distance.threshold	Subsequent fixations occurring withing this distance are merged. Set to 0 if you don't want to merge fixations.
merge.ms.threshold	Subsequent fixations occuring within this time window and distance specified by distance.threshold are merged. Set to 0 if you don't want to merge fixations.
missing.samples.threshold	Remove fixations with a higher proportion of missing samples. Range 0 to 1.

Value

list including separate data frames for fixations and sample-by-sample data including filtered and unfiltered data. The fixations data frame gives onset, offset, x, y, RMSD and missing samples of each fixation.

Examples

ivt_data <- ivt_filter(sample.data.processed, velocity.threshold = 30, min.fixation.duration = 40)

kollaR documentation built on April 13, 2025, 5:11 p.m.