Adjust the onset and offset of fixations to avoid misclassification of saccade samples as belonging to fixations

Description

Shrink the period classified as a fixation by removing samples close to the onset and offset with excessive differences from the fixation center. This reduces the risk that samples belonging to saccades are misclassified as belonging to a fixation. The function is used internally by other functions and should typically not be called outside of them.

adjust_fixation_timing starts by calculating the median (MD) and MAD of the absolute distances from the fixation center of all included samples. The fixation onset is shifted forwards to the first sample with a distance to the fixation center under t* MAD + MD where t is specified by the input parameter threshold. Analogously, fixation offset is shifted backwards to the last included sample with distance to the fixation center under t* MAD + MD

Usage

adjust_fixation_timing(
  fixation.candidate.starts,
  fixation.candidate.stops,
  x,
  y,
  threshold = 3
)

Arguments

Value

data frame with adjusted first and last row of the fixation

Adaptive velocity-based algorithm for saccade and fixation detection

Description

The function is based on a procedure suggested by Nyström and Holmqvist 2010. Behavior Research Methods, 42, 188-204. Velocity thresholds for saccade onset and offset are adapted to the specific data at hand. Please see Nyström and Holmqvist (2010) for a description of this procedure. STEP 1: The function starts by identifying peak velocities larger than an initial threshold (peak threshold, specified by the parameter peak.threshold.start), and then iteratively adjusts this threshold through the following steps: A) The mean (M) and standard deviation (SD) of the velocities of all samples with velocties below the peak threshold are calculated. B) the updated peak threshold is defined as M +6SD. C) Steps A-B are repeated until the difference between the old and new peak threshold is < 1 degree. D) The threshold for identification of saccade onsets (saccade onset threshold) is defined as M + onset.threshold *SD. For each segment in the data with velocities above peak threshold, go through steps 2-3:

STEP 2: Saccade onset is defined by searching backwards from the leftmost sample with velocity above peak threshold to the first sample with a velocity above saccade onset threshold and a higher velocity than the previous sample. STEP 3: Define saccade offset threshold as a weighted sum of a) the saccade onset threshold and b) the 'local noise factor' defined as mean + 3SD of sample-to-sample velocity during a period just before saccade onset. This period has the same length as the minimum fixation duration (specified by the parameter min.fixation.duration) Saccade onset is defined by searching forward from the rightmost sample with a velocity above peak threshold to the first sample with a velocity below saccade offset threshold and a lower velocity than the previous sample. STEP 4: Fixations are defined as periods between saccades (as in the I-VT algorithm)

If the function can not detect a sample which fulfills both the threshold criterion and the acceleration/deceleration criterion during step 2-3, it will try to find a sample that fulfills the threshold criterion. If this fails, the saccade is discarded.

The input data should be pre-processed (e.g., noise removal and interpolation over gaps)

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, and gaze coordinates before ("raw") and after fixation detection. 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

algorithm_adaptive(
  gaze,
  min.fixation.duration = 40,
  min.saccade.duration = 10,
  xcol = "x.raw",
  ycol = "y.raw",
  save.velocity.profiles = FALSE,
  missing.samples.threshold = 0.5,
  merge.ms.threshold = 75,
  distance.threshold = 0.7,
  alpha = 0.7,
  beta = 0.3,
  one_degree = 40,
  velocity.filter.ms = 10,
  peak.threshold.start = 200,
  onset.threshold.sd = 3,
  min.period.ms = 40,
  margin.ms = 3,
  trim.fixations = TRUE,
  trim.dispersion.threshold = NA
)

Arguments

Value

list including separate data frames for fixations, saccades, and sample-by-sample data

Fixation detection by two-means clustering

Description

Identify fixations in a gaze matrix using identification by two-means clustering. The algorithm is based on Hessels et al 2017. Behavior research methods, 49, 1802-1823. Data from the left and right eye are not processed separately. Adjust your analysis scripts to include this steps if you want the algorithm to include this step, as in Hessels et al 2017. 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. X and y coordinates can be in pixels or proportion of the screen. Make sure that the parameter one_degree is consistent with the format of your data. The output data is a list with two data frames: fixations includes all detected fixations with coordinates, duration and a number of other metrics, filt.gaze is a sample-by-sample data frame with time stamps, raw gaze coordinates (e.g., before fixation detection) and fixation coordinates. If the input downsampling.factors is not empty, transition weights will be calculated based on the data in the original sampling rate and data at all sampling rate specified in this variable. According to Hessels et al 2017, this step makes the analysis less vulnerable to noise in the data. If the parameter threshold.on.off is not NA, the onsets and offsets of fixations will be shifted to exclude samples at the margins with a larger absolute distance from the fixation centroid than a threshold value. The threshold value is defined as the median of all absolute distances from the centroid plus threshold.on.off * MAD of the absolute distances. Default threshold is 3. Samples with large distances from the fixation centroid right at the onset and offset of a fixation may belong to a saccade.

Usage

algorithm_i2mc(
  gaze_raw,
  windowlength.ms = 200,
  distance.threshold = 0.7,
  one_degree = 40,
  window.step.size = 6,
  min.fixation.duration = 40,
  weight.threshold = 2,
  xcol = "x.raw",
  ycol = "y.raw",
  merge.ms.threshold = 40,
  downsampling.factors = NA,
  missing.samples.threshold = 0.5,
  threshold.on.off = 3
)

Arguments

Value

list including separate data frames for fixations and sample-by-sample data including gaze coordinates before ("raw") and after fixation detection. The "fixations" data frame gives onset, offset, x, y, sample-to-sample root-mean-square deviations (RMSD, precision), RMSD from fixation centroid, and missing samples of each fixation.

Examples

gaze <- algorithm_i2mc(sample.data.processed)

Dispersion-based fixation detection algorithm (I-DT)

Description

Apply a dispersion-based fixation (I-DT) filter to the eye tracking data. The algorithm identifies fixations as samples clustering within a spatial area. The procedure is described in Blignaut 2009 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 preprocess_gaze for this. Timestamps are assumed to be in milliseconds. The output data is a list with two data frames: fixations includes all detected fixations with coordinates, duration and a number of other metrics, filt.gaze is a sample-by-sample data frame with time stamps, raw gaze coordinates (e.g., before event detection) and fixation coordinates. The function can be very slow for long recordings and/or data recorded at high sampling rates.

Usage

algorithm_idt(
  gaze_raw,
  one_degree = 40,
  dispersion.threshold = 1,
  min.duration = 50,
  xcol = "x.raw",
  ycol = "y.raw",
  distance.threshold = 0.7,
  merge.ms.threshold = 75,
  missing.samples.threshold = 0.5
)

Arguments

Value

list including separate data frames for fixations and sample-by-sample data including gaze coordinates before and after fixation detection. The fixations data frame includes onset, offset, x, y, sample-to-sample root-mean-square deviations (RMSD, precision), RMSD from fixation centroid, and missing samples of each fixation.

I-VT algorithm for fixation and saccade detection

Description

Apply an I-VT event detection algorithm 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 preprocess_gaze for this. Timestamps are assumed to be in milliseconds. X and y coordinates can be in pixels or proportion of the screen depending on the format of your data. Make sure that the parameter one_degree matches the unit of your data 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, and gaze coordinates before ("raw") and after fixation detection. 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

algorithm_ivt(
  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,
  trim.fixations = FALSE,
  trim.dispersion.threshold = NA
)

Arguments

Value

list including separate data frames for fixations and sample-by-sample data including x and y coordinates before and after fixation detection. The fixations data frame gives onset, offset, x, y, sample-to-sample RMSD (precision),root-mean-square deviations from fixation centroid, and missing samples of each fixation.

Examples

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

Create GIF animation of fixations on a stimulus images

Description

This function plots and returns a .gif showing fixations on a background with one or multiple images, typically the stimuli. The interval to plot is defined by sample numbers. Fixations must have the variables x, y, and onset. The function works with .jpg images. If paths to multiple images are given, all will be displayed. Fixations are shown on a white background if no background images are defined. .gif images can be saved to a file. Gaze data are plotted on a reversed y-axis where x and y are 0 is the upper left corner, corresponding to the structure of data from Tobii eye trackers. If there are multiple participants specified in the variable id, each participant will get a unique color. You may get an error message if some participants lack data during single frames. This is usually no cause for concern.

Usage

animated_fixation_plot(
  gazedata,
  xres = 1920,
  yres = 1080,
  plot.onset,
  plot.offset,
  background.images = NA,
  filename = "scanpath.gif",
  save.gif = FALSE,
  gif.dpi = 300,
  gazepoint.size = 2,
  n.loops = 1,
  show.legend = TRUE,
  id_color_map = NA,
  resolution.scaling = 0.5,
  framerate = 10,
  show.progress = TRUE
)

Arguments

Value

a magick animation of raw and fixated values plotted on the y axis and sample number on the x axis

Test whether a gaze coordinates are within or outside a rectangular or elliptical AOI. The aois df must contain the variables x0, x1, y0 and y1. x0 is the minimum x value, y0 the minimum y value. x1 the maximum x value. y1 the maximum y value and type where rect means that the AOI is a rectangle and circle that the AOI is a circle or ellipse If a column called name is present, the output for each AOI will be labelled accordingly. Otherwise, the output will be labelled according to the order of the AOI in the data frame. The df 'gaze' must contain the variables onset, duration, x, and y. Latency will be defined as the value in onset of the first detected gaze coordinate in the AOI Make sure that the timestamps are correct! The function can be used with gaze data either fixations, saccades, or single samples. Note that the output variables are not equally relevant for all types of gaze data. For example, both total duration and latency are relevant in many analyses focusing on fixations, but total duration may be less relevant in analyses of saccades.

Description

Test whether a gaze coordinates are within or outside a rectangular or elliptical AOI. The aois df must contain the variables x0, x1, y0 and y1. x0 is the minimum x value, y0 the minimum y value. x1 the maximum x value. y1 the maximum y value and type where rect means that the AOI is a rectangle and circle that the AOI is a circle or ellipse If a column called name is present, the output for each AOI will be labelled accordingly. Otherwise, the output will be labelled according to the order of the AOI in the data frame. The df 'gaze' must contain the variables onset, duration, x, and y. Latency will be defined as the value in onset of the first detected gaze coordinate in the AOI Make sure that the timestamps are correct! The function can be used with gaze data either fixations, saccades, or single samples. Note that the output variables are not equally relevant for all types of gaze data. For example, both total duration and latency are relevant in many analyses focusing on fixations, but total duration may be less relevant in analyses of saccades.

Usage

aoi_test(gaze, aois, outside = FALSE)

Arguments

Value

data frame with total duration, number of occurrences and latency to first detected gaze coordinates for each AOI. Data are in long format.

Fixation detection by two-means clustering

Description

Identify fixations in a gaze matrix using identification by two-means clustering. The algorithm is based on Hessels et al 2017. Behavior research methods, 49, 1802-1823. Data from the left and right eye are not processed separately. Adjust your analysis scripts to include this steps if you want the algorithm to include this step, as in Hessels et al 2017. 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. X and y coordinates can be in pixels or proportion of the screen. Make sure that the parameter one_degree is consistent with the format of your data! The output data is a list with two data frames: fixations includes all detected fixations with coordinates, duration and a number of other metrics, filt.gaze is a sample-by-sample data frame with time stamps, gaze coordinates before fixation detection ("raw") for and fixation coordinates. If the input downsampling.factors is not empty, transition weights will be calculated based on the data in the original sampling rate and data at all sampling rate specified in this variable. According to Hessels et al 2017, this step makes the analysis less vulnerable to noise in the data.

Usage

cluster2m(
  gaze_raw,
  windowlength.ms = 200,
  distance.threshold = 0.7,
  one_degree = 40,
  window.step.size = 6,
  min.fixation.duration = 40,
  weight.threshold = 2,
  xcol = "x.raw",
  ycol = "y.raw",
  merge.ms.threshold = 40,
  downsampling.factors = NA,
  missing.samples.threshold = 0.5
)

Arguments

Value

list including separate data frames for fixations and sample-by-sample data including gaze coordinates before fixation classification ("raw") and fixation coordinates. The "fixations" data frame gives onset, offset, x, y, sample-to-sample root-mean-square deviations (RMSD, precision), RMSD from fixation centroid, and missing samples of each fixation.

Examples

gaze <- cluster2m(sample.data.processed)

Downsample gaze

Description

This function downs-samples gaze by a specified factor. Data are down-sampled by splitting the data in bins and calculating the mean of each bin.

Usage

downsample_gaze(data_in, ds.factor, xcol = "x", ycol = "y")

Arguments

Value

Data frame with downsampled gaze data. The output variables are x, y, and the numbers of the first and last samples of the original data frame included in the bin.

Draw one or more areas of interest, AOIs, on a stimulus image and save to the R prompt. The input is the path to a 2D image. Supported file formats: JPEG, BMP, PNG. The function returns a data frame with all saved AOIs. By default, AOIs are drawn in a coordinate system where y is 0 in the lower extreme of the image, e.g., an ascending y axis. Tobii eye trackers use a coordinate system with a descending y-axis, e.g., x and y are 0 in the upper left corner of the image. Make sure that your AOIS match the coordinate system of your eye tracker output. By setting the parameter reverse.y.axis to TRUE, the saved AOIs will be reformatted to fit a coordinate system with a descending y-axis. All AOIS have the variables x0, x1, y0 and y1. x0 is the minimum x value, y0 the minimum y value. x1 the maximum x value. y1 the maximum y value

Description

Draw one or more areas of interest, AOIs, on a stimulus image and save to the R prompt. The input is the path to a 2D image. Supported file formats: JPEG, BMP, PNG. The function returns a data frame with all saved AOIs. By default, AOIs are drawn in a coordinate system where y is 0 in the lower extreme of the image, e.g., an ascending y axis. Tobii eye trackers use a coordinate system with a descending y-axis, e.g., x and y are 0 in the upper left corner of the image. Make sure that your AOIS match the coordinate system of your eye tracker output. By setting the parameter reverse.y.axis to TRUE, the saved AOIs will be reformatted to fit a coordinate system with a descending y-axis. All AOIS have the variables x0, x1, y0 and y1. x0 is the minimum x value, y0 the minimum y value. x1 the maximum x value. y1 the maximum y value

Usage

draw_aois(image.path, reverse.y.axis = FALSE)

Arguments

Value

data frame with type and coordinates of drawn AOIs

Plot fixations vs. individual sample coordinates in 2D space. In the current release, filt_plot_2d is a wrapper around fixation_plot_2d which accepts the same arguments.

Description

This function plots and returns a ggplot2 figure showing fixations and individual gaze coordinates plotted against time. The interval to plot can be defined as a proportion of the data frame or by sample numbers. This function uses one data.frame with fixations and one with sample-by-sample raw data

Usage

filt_plot_2d(
  raw.data,
  fixation.data,
  plot.window = c(NA, NA),
  raw.columns = c("x.raw", "y.raw"),
  fixation.columns = c("x", "y"),
  fixation.radius = 40,
  xres = 1920,
  yres = 1080,
  order.vertical = FALSE,
  verbose = TRUE
)

Arguments

Value

a ggplot of raw and fixated values plotted on the y axis and sample number on the x axis

Plot fixation filtered vs. raw gaze coordinates. This function will be replaced by fixation_plot_temporal in future releases. It is currently a wrapper around fixation_plot_temporal accepting the same arguments.

Description

This function plots and returns a ggplot2 figure showing two time series of gaze coordinates plotted against time. The interval to plot can be defined as a proportion of the data frame, by timestamps, or by sample numbers. Use this function to plot data before and after processing or filtering to examine their effects. For example, unprocessed x or y coordinates can be plotted against x and y coordinates following pre-processing and/or event detection with a fixation detection algorithm Either the x or the y vector is plotted

Usage

filt_plot_temporal(
  data_in,
  plot.window = c(NA, NA),
  var1 = "x.raw",
  var2 = "x",
  x.index.var = "sample.index",
  verbose = TRUE
)

Arguments

Value

a ggplot with gaze coordinates plotted on the y axis and sample number on the x axis

Examples

new.plot <- filt_plot_temporal(sample.data.classified, plot.window = c(1000, 2000))

Find transition weights for each sample in a gaze matrix.

Description

This function is used internally by the function algorithm_i2mc

Usage

find.transition.weights(data_in, window.step.size = 6, windowsize)

Arguments

Value

transition weights.

Find subsequent periods in a vector with values below a threshold. Used internally by the function suggest_threshold

Description

This function is used internally by suggest_threshold.

Usage

find.valid.periods(data_in, threshold, min_samples, margin = 0)

Arguments

Plot fixations vs. individual sample coordinates in 2D space.

Description

This function plots and returns a ggplot2 figure showing fixations and individual gaze coordinates plotted against time. The interval to plot can be defined as a proportion of the data frame or by sample numbers. This function uses one data.frame with fixations and one with sample-by-sample raw data

Usage

fixation_plot_2d(
  raw.data,
  fixation.data,
  plot.window = c(NA, NA),
  raw.columns = c("x.raw", "y.raw"),
  fixation.columns = c("x", "y"),
  fixation.radius = 40,
  xres = 1920,
  yres = 1080,
  xmin = 1,
  ymin = 1,
  order.vertical = FALSE,
  font.size = 15,
  verbose = TRUE
)

Arguments

Value

a ggplot of raw and fixated values plotted on the y axis and sample number on the x axis

Plot fixation classified vs. raw gaze coordinates

Description

This function plots and returns a ggplot2 figure showing two time series of gaze coordinates plotted against time. The interval to plot can be defined as a proportion of the data frame, by timestamps, or by sample numbers. Use this function to plot data before and after processing or filtering to examine their effects. For example, unprocessed x or y coordinates can be plotted against x and y coordinates following pre-processing and/or event detection with a fixation detection algorithm Either the x or the y vector is plotted

Usage

fixation_plot_temporal(
  data_in,
  plot.window = c(NA, NA),
  var1 = "x.raw",
  var2 = "x",
  x.index.var = "sample.index",
  verbose = TRUE
)

Arguments

Value

a ggplot with gaze coordinates plotted on the y axis and sample number on the x axis

Examples

new.plot <- fixation_plot_temporal(sample.data.classified, plot.window = c(1000, 2000))

Plot fixation classified vs. raw gaze coordinate time series

Description

This function plots and returns a ggplot2 figure showing time series of gaze coordinates plotted against time. The interval to plot must be specified in the same unit as the vaiable specified in the input variable x.index.var. By default, this variable is called timestamp. Use this function to compare the raw gaze coordinates to the output from one or more fixation classification algorithms. Either the X or the Y coordinates are plotted. If the variable specified in the parameter algorithm.name is present in the input data AND contains more than one unique category, you will get subplots for each category. For example, if the input data contains fixation and raw coordinates for data from the I-VT and I2MC algorithms, each will be plotted in a separate subplot. Note that the X index variable (time stamps or sample number) must be the same.

Usage

fixation_plot_ts(
  data_in,
  plot.window = c(NA, NA),
  x.index.var = "timestamp",
  var1 = "x.raw",
  var2 = "x",
  xres = 1920,
  yres = 1080,
  verbose = TRUE,
  algorithm.name = "fixation.algorithm",
  ylim = NA,
  font.size = 15
)

Arguments

Value

a ggplot with gaze coordinates plotted on the y axis and sample number on the x axis

Examples

new.plot <- fixation_plot_ts (sample.data.classified, plot.window = c(1000, 2000))

Dispersion-based fixation detection algorithm (I-DT)

Description

This function will be replaced by the function algorithm_idt in subsequent versions. The two functions take the same input arguments.idt_filter is a wrapper around idt_algorithm.

Apply a dispersion-based fixation (I-DT) detection algorithm to the eye tracking data. The algorithm identifies fixations as samples clustering within a spatial area. The procedure is described in Blignaut 2009 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. The output data is a list with two data frames: fixations includes all detected fixations with coordinates, duration and a number of other metrics, filt.gaze is a sample-by-sample data frame with time stamps, raw gaze coordinated and fixation coordinates. The function can be slow for long recordings and/or data recorded at high sampling rates.

Usage

idt_filter(
  gaze_raw,
  one_degree = 40,
  dispersion.threshold = 1,
  min.duration = 50,
  xcol = "x.raw",
  ycol = "y.raw",
  distance.threshold = 0.7,
  merge.ms.threshold = 75,
  missing.samples.threshold = 0.5
)

Arguments

Value

list including separate data frames for fixations and sample-by-sample data including gaze coordinates with and without fixation detection. The fixations data frame includes onset, offset, x, y, sample-to-sample root-mean-square deviations (RMSD, precision), RMSD from fixation centroid, and missing samples of each fixation.

Examples

idt_data <- idt_filter(sample.data.processed)

Interpolate over gaps (subsequent NAs) in vector.

Description

Interpolate over gaps (subsequent NAs) in vector.

Usage

interpolate_with_margin(data_in, marg, max_gap)

Arguments

Value

vector with interpolated gaps

I-VT algorithm for fixation and saccade detection

Description

Apply an I-VT filter to the eye tracking data. This function is a wrapper around the function ivt_algorithm. It will be replaced by algorithm_ivt in future versions. 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. 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, and gaze coordinates before ("raw") and after fixation detection. 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,
  trim.fixations = FALSE,
  trim.dispersion.threshold = NA
)

Arguments

Value

list including separate data frames for fixations and sample-by-sample data including gaze coordinates before and after fixation detection. The fixations data frame gives onset, offset, x, y, sample-to-sample root-mean-square deviations (RMSD, precision), RMSD from fixation centroid, and missing samples of each fixation.

Examples

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

Fixation and Saccade Detection, Visualization, and Analysis of Eye Tracking Data

Description

Functions for analyzing eye-tracking data, including event detection (sometimes referred to as fixation filtering), visualizations, and area of interest (AOI) based analyses. See separate documentation for each function. Make sure it works with your data. Currently included algoritms are I-VT, I-DT, adaptive velocity threshold and two-means clustering). The principles underlying I-VT and I-DT filters are described in Salvucci & Goldberg (2000,doi:10.1145/355017.355028). Two-means clustering is described in Hessels et al. (2017, doi:10.3758/s13428-016-0822-1). The adaptive velocity algorithm is described in Nyström and Holmqvist (2010, doi:10.3758/BRM.42.1.188)

Details

Overview of functions: Pre-processing (smoothing, interpolation, downsampling):'preprocess_gaze', 'downsample_gaze'

Fixation and Saccade Classification (Fixation Filters)**: 'algorithm_ivt', 'algorithm_idt', 'algorithm_i2mc', 'algorithm_adaptive'

Fixation and Post-Processing)**: 'merge_adjacent_fixations', 'trim_fixations'

Visualization of Output from Fixation and Saccade Detection and Preprocessing Algorithms: 'fixation_plot_ts', 'fixation_plot_temporal', 'fixation_plot_2d', 'plot_velocity_profiles', 'plot_sample_velocity', 'plot_algorithm_results'

Visualization of Gaze Data: 'static_plot', 'animated_fixation_plot'

AOI Based Analyses: 'draw_aoi', 'aoi_test'

Author(s)

Johan Lundin Kleberg johan.lundin.kleberg@su.se

Merge adjacent fixations

Description

Merge fixations which appear close in space and time. This function is called by other functions and typically not used outside them

Usage

merge_adjacent_fixations(
  fixations,
  gaze_raw,
  distance.threshold = 0.5,
  ms.threshold = 75,
  one_degree = 40,
  xcol = "x.raw",
  ycol = "y.raw"
)

Arguments

Value

A new data frame with fixations

Plot vdescriptives one or more fixation detection algorithms

Description

This function visualizes validity measures of fixations detected with one or more fixation detection algorithms. The function is tested for fixation data frames generated with kollaR event detection algorithms. By default, the function can plot Root Mean Square Deviations of subsequent samples within the detected fixations (precision), the RMSD from the fixation centroid, fixation duration and the proportion of missing raw samples. The output data is a ggplot which can be modified further outside the function. If you want to use this function to compare more than one fixation detection algorithms, combine them using the function rbind in base R. For example, rbind(my_data1[["fixations"]], my_data2[["fixations"]]) would generate a combined data frame with the fixations detected by two event classification procedures.

Usage

plot_algorithm_results(data_in, plot.variable = "rmsd")

Arguments

Value

A ggplot with visualizations of the selected validity measure

Examples

plot_algorithm_results(data_in = sample.data.fixations, plot.variable = "rmsd")

Plot descriptives from one or more fixation detection algorithms

Description

This function visualizes validity measures of fixations detected with one or more fixation detection algorithms. The function is tested for fixation data frames generated with kollaR event detection algorithms. By default, the function can plot Root Mean Square Deviations of detected fixations, fixation duration and the proportion of missing raw samples. The output data is a ggplot which can be modified further outside the function. If you want to use this function to compare more than one fixation detection algorithms, combine them using the function rbind in base R. For example, rbind(my_data1[["fixations"]], my_data2[["fixations"]]) would generate a combined data frame with the fixations detected by two event classification procedures. This function will be replaced by 'plot_algorithm_results' in future versions.

Usage

plot_filter_results(data_in, plot.variable = "rmsd")

Arguments

Value

A ggplot with visualizations of the selected validity measure

Examples

plot_filter_results(data_in = sample.data.fixations, plot.variable = "rmsd")

Plot the sample-to-sample velocity of eye tracking data.

Description

This function visualizes the sample-to-sample velocity in a period of eye tracking data. This can be helpful when determining a suitable velocity threshold for saccade detection 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 plot of sample-to-sample velocity in the selected interval.

Usage

plot_sample_velocity(
  data_in,
  velocity.filter.ms = 20,
  plot.window = c(NA, NA),
  xcol = "x.raw",
  ycol = "y.raw",
  threshold.line = NA,
  one_degree = 40,
  verbose = TRUE
)

Arguments

Value

A ggplot showing the sample-to-sample velocity of the selected data interval

Examples

plot_sample_velocity(data_in = sample.data.processed, threshold.line = 35)

Create ggplot of saccade velocity profiles

Description

This function plots and returns a ggplot showing velocity profiles of saccades plotted against time. Saccades should be generated with the ivt.filter functions with the save.velosity.profiles parameter set to TRUE. The interval to plot is defined by saccade number as they appear in the sacccades data frame.

Usage

plot_velocity_profiles(saccades, onset = NA, offset = NA, verbose = TRUE)

Arguments

Value

ggplot with velocity profiles

Examples

new.plot <- plot_velocity_profiles(sample.data.saccades, onset = 10, offset = 20)

Interpolation and smoothing of gaze-vector

Description

Pre-processing gaze Interpolate over gaps in data and smooth the x and y vectors using a moving average filter. The gaze vector must contain the variables timestamp, and variables containing unfiltered x and y coordinates. Default names: x.raw and y.raw. Timestamps are assumed to be in milliseconds. The unprocessed x and y variables are kept under the names x.unprocessed and y.unprocessed for comparison. The function will add the variable timestamp.t to the data frame before returning. This is a theoretical timestamp based on the detected median sample-to-sample timestamp difference as compared to the actual registered time stamps in the data. This can be useful in some validation analyses.

Usage

preprocess_gaze(
  gaze_raw,
  max_gap_ms = 75,
  marg_ms = 5,
  filter_ms = 15,
  xcol = "x.raw",
  ycol = "y.raw"
)

Arguments

Value

data frame with gaze data after interpolation and filtering

Examples

processed_gaze <- preprocess_gaze(sample.data.unprocessed)

Interpolation and smoothing of gaze-vector. This function will be replaced by preprocess_gaze in future versions. process_gaze is a wrapper around preprocess gaze (the two functions produce the same result)

Description

Pre-processing of gaze. Interpolate over gaps in data and smooth the x and y vectors using a moving average filter. The gaze vector must contain the variables timestamp, and variables containing unfiltered x and y coordinates. Default names: x.raw and y.raw. Timestamps are assumed to be in milliseconds. The unprocessed x and y variables are kept under the names x.unprocessed and y.unprocessed for comparison. The function will add the variable timestamp.t to the data frame before returning. This is a theoretical timestamp based on the detected median sample-to-sample timestamp difference as compared to the actual registered time stamps in the data. This can be useful in some validation analyses.

Usage

process_gaze(
  gaze_raw,
  max_gap_ms = 75,
  marg_ms = 5,
  filter_ms = 15,
  xcol = "x.raw",
  ycol = "y.raw"
)

Arguments

Value

data frame with gaze data after interpolation and filtering

Examples

processed_gaze <- process_gaze(sample.data.unprocessed)

Sample-to-sample raw and fixation classified data from 1 individual

Description

This dataset contains sample-to-sample data from 1 individuals during a free viewing tasks. Data were recorded at 1200 Hz using a Tobii Pro Spectrum eye tracker. Fixations were classified with the I-VT algorithm with a velocity threshold set to 30 degrees/seconds and default settings in the function algorithm_ivt

Usage

sample.data.classified

Format

A data frame

x

fixation position x

y

fixation position y

x.raw

fixation position x

y.raw

fixation position y

timestamp

timestamp in milliseconds

Source

The dataset was stored in the package at 'data/example_data.RData'

Fixations from 1 individual

Description

This dataset contains fixation data from 1 individuals during a free viewing tasks. Data were recorded at 1200 Hz using a Tobii Pro Spectrum eye tracker

Usage

sample.data.fixation1

Format

A data frame

x

fixation position x

y

fixation position y

duration

duration of fixation in milliseconds

onset

onset of fixation in milliseconds

offset

offset of fixation in milliseconds

rmsd

Sample-to-sample root mean square deviation of all samples

rms.from.center

Root means square deviation of all included samples from the centroid of the fixation

missing.samples

proportion of missing samples

fixation.algorithm

Name of the fixation filter algorithm

threshold

Threshold setting for the fixation classification algorithm

id

Participant id

Source

The dataset was stored in the package at 'data/example_data.RData'

Fixations from 7 individuals

Description

This dataset contains fixation data from 7 individuals during a free viewing tasks. Data were recorded at 1200 Hz using a Tobii Pro Spectrum eye tracker

Usage

sample.data.fixations

Format

A data frame

x

fixation position x

y

fixation position y

duration

duration of fixation in milliseconds

onset

onset of fixation in milliseconds

offset

offset of fixation in milliseconds

rmsd

Sample-to-sample root mean square deviation of all samples

rms.from.center

Root means square deviation of all included samples from the centroid of the fixation

missing.samples

proportion of missing samples

fixation.algorithm

Name of the fixation filter algorithm

threshold

Threshold setting for the fixation classification algorithm

id

Participant id

Source

The dataset was stored in the package at 'data/example_data.RData'

Pre-processed sample-by-sample example data

Description

This dataset contains data from 1 individuals during a free viewing tasks after pre-processing. Data were recorded at 1200 Hz using a Tobii Pro Spectrum eye tracker

Usage

sample.data.processed

Format

A data frame

id

participant number

timestamp

timestamp in ms recorded by the eye tracker

x.raw

gaze position x

y.raw

gaze position y

x.unprocessed

copy of gaze position x before preprocessing

y.unprocessed

copy of gaze position y before preprocessing

timestamp.t

"'Theoretical timestamp' for comparison."

sample

sample nr in recording

Source

The dataset was stored in the package at 'data/example_data.RData'

Saccades from 3 individuals

Description

This dataset contains saccade data from 3 individuals during a free viewing tasks. Data were recorded at 1200 Hz using a Tobii Pro Spectrum eye tracker

Usage

sample.data.saccades

Format

A data frame

onset

onset of the saccade in ms

x.onset

gaze position x at onset

y.onset

gaze position y at onset

offset

offset of the saccade in ms

x.offset

gaze position x at offset

y.offset

gaze position y at offset

duration

duration of saccade in ms

amplitude

amplitude of saccade in degrees

peak.velocity

peak velocity of saccade

velocity.profile

velocity profile

missing.samples

proportion of missing samples

id

participant number

Source

The dataset was stored in the package at 'data/example_data.RData'

Unprocessed sample-by-sample example data

Description

This dataset contains data from 1 individual during a free viewing tasks before pre-processing. Data were recorded at 1200 Hz using a Tobii Pro Spectrum eye tracker

Usage

sample.data.unprocessed

Format

A data frame

id

participant number

timestamp

timestamp in ms recorded by the eye tracker

x.raw

gaze position x

y.raw

gaze position y

Source

The dataset was stored in the package at 'data/example_data.RData'

Plot fixations in 2D space overlaied on a stimulus image

Description

This function plots and returns a ggplot2 figure showing fixations on a background with one or multiple images, typically the stimuli. Data can represent one or multiple participants The interval to plot is defined by sample numbers. Fixations must have the variables x, y, and onset. The function is tested with .jpg-images. If paths to multiple images are given, all will be displayed. Fixations are shown on a white background if no background images are defined

Usage

static_plot(
  gazedata,
  xres = 1920,
  yres = 1080,
  plot.onset,
  plot.offset,
  background.images = NA,
  show.legend = TRUE,
  group.by = NA,
  gazepoint.size = 4,
  id_color_map = NA,
  connect.lines = TRUE,
  verbose = TRUE
)

Arguments

Value

a ggplot of raw and fixated values plotted on the y axis and sample number on the x axis

Data-driven identification of threshold parameters for adaptive veloctity-based saccade detection.

Description

The function is based on a procedure suggested by Nyström and Holmqvist 2010. Behavior Research Methods, 42, 188-204. The function can be used to identify specific thresholds for saccade onset for individuals and/or segments of the data, as an alternative to using the same thresholds for each participants. It is used in kollaR by the function 'algorithm_adaptive'

Peak velocity and saccade amplitude are typically highly postively correlated. It is therefore important to consider that differences in gaze behavior between individuals and/or data segment may lead to differences in proposed saccade onset velocity threshold. #' The input data should be pre-processed (e.g., noise removal and interpolation over gaps) The output is a list with three cells: "peak.threshold" and "onset.threshold" are parameters used by the function algorithm_adaptive (see Nyström and Holmqvist 2010 for details). "velocity" is a data frame with sample-to-sample velocity in the unit specified by the parameter one_degree

Usage

suggest_threshold(
  gaze,
  velocity.filter.ms = 10,
  one_degree = 40,
  ycol = "y.raw",
  xcol = "x.raw",
  peak.threshold.start = 130,
  onset.threshold.sd = 3,
  min.period.ms = 40,
  margin.ms = 3
)

Arguments

Value

list including separate data frames for proposed saccade onset threshold, peak threshold, and sample-to-sample velocity

Summarize fixation statistics

Description

Summarize descriptives for a fixation defined by onset and offset rows in the data. Used internally by event classification functions.

Usage

summarize_fixation_metrics(
  fixation.candidate.starts,
  fixation.candidate.stops,
  x,
  y,
  timestamp,
  one_degree = 40
)

Arguments

Value

data frame with fixation descriptives

Adjust the onset and offset of fixations to avoid misclassification of saccade samples as belonging to fixations

Description

Adjust the onset and offset of all fixations in a data frame (The function adjust_fixation_timing does this for a single fixation).

Shrink the period classified as a fixation by removing samples at the onset and offset with excessive differences from the fixation center or which are missing (X or Y are NA). This reduces the risk that samples belonging to saccades are misclassified as belonging to a fixation. Please note that this procedure is included by default in the event classification algorithm 'alogorithm_i2mc' (see documentation for this function for details)

The procedure starts by calculating the median (MD) and MAD of the absolute distances from the fixation center of all included samples. The fixation onset is shifted forwards to the first sample with a distance to the fixation center under t* MAD + MD where t is specified by the input parameter threshold. Analogously, fixation offset is shifted backwards to the last included sample with distance to the fixation center under t* MAD + MD

trim_fixations will look for variables called 'fixation.algorithm' and 'threshold' in the data frame 'fixations'. These columns are produced by kollaR event classification algorithms. If they are found, they will be transfered to the output data frame.

Usage

trim_fixations(
  fixations,
  gaze,
  xcol = "x.raw",
  ycol = "y.raw",
  threshold = 3,
  one_degree = 40
)

Arguments

Value

data frame with fixations after adjustment of onset and offset