cluster2m: Fixation detection by two-means clustering

In kollaR: Event Classification, Visualization and Analysis of Eye Tracking 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, 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

gaze_raw	Data frame with gaze data before fixation detection. Include the variable timestamp with timing in ms and columns with x and y data as specified by the parameters xcol and ycol or their default values
windowlength.ms	Length of the moving analysis windows
distance.threshold	Subsequent fixations occurring withing this distance are merged. Set to 0 if you do not want to merge fixations.
one_degree	One degree of the visual field in the unit of the raw x and y coordinates, typically pixels or proportion of the screen. Make sure that the setting matches the format of your data
window.step.size	Distance between starting points of subsequent analysis windows in samples
min.fixation.duration	Minimum duration of accepted fixations. Shorter fixations are discarded
weight.threshold	Samples with a transition weight exceeding it are candidates for fixation detection.
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
merge.ms.threshold	Only fixations occurring within this time window in milliseconds are merged
downsampling.factors	Factors to downsample the data by in calculating fixation weights. If downsampling.factors has the values c(10, 2), transition weights will be calculated base on data in the original sampling rate as well as the two downsampled data sets.
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 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)

kollaR documentation built on June 8, 2025, 10:03 a.m.