gazeHMM: Classify Gaze Data into Eye Movement Events
In maltelueken/gazeHMM: Classify Gaze Data With a Hidden Markov Model

Description Usage Arguments Details Value Examples

The algorithm 'gazeHMM' for classifying eye-tracking data into eye movement events using a hidden Markov model.

gazeHMM(
  x,
  y,
  t,
  unit = "px",
  res,
  dim,
  dist,
  fr,
  blink = NULL,
  b.win = 0.05,
  sg.order = 3,
  sg.length = 5,
  nstates,
  respstart,
  trstart,
  instart,
  sf = c(10, 10),
  random.respstart = T,
  start.seed = NULL,
  fit.control = em.control(maxit = 5000, random.start = F),
  min.sac = 0.01
)

`x`	Numeric vector of raw x coordinates for each gaze samples.
`y`	Numeric vector of raw y coordinates for each gaze samples.
`t`	Numeric vector of time stamps for each gaze sample.
`unit`	Character string indicating the unit of coordinates (either 'px' or 'va').
`res`	Screen resolution (in px).
`dim`	Screen dimensions (in mm).
`dist`	Distance between subject and screen (in mm).
`fr`	Sampling rate of the eye-tracker (in Hz).
`blink`	Either a numeric vector of length two indicating the x and y coordinates for blink samples or a logical vector with the same length as `x`, `y`, and `t` indicating blink samples.
`b.win`	Time window around blink samples that are to be ignored (i.e., set to NA; in s).
`sg.order`	Order of the Savitzky-Golay filter.
`sg.length`	Length of the Savitzky-Golay filter (must be odd).
`nstates`	Number of states in the hidden Markov model.
`respstart`	Starting values for the response model in the hidden Markov model.
`trstart`	Starting values for the transition model in the hidden Markov model.
`instart`	Starting values for the initial state model in the hidden Markov model.
`sf`	Vector of length two indicating by which factor velocity and acceleration data will be divided.
`random.respstart`	Logical indicating whether random starting values will be generated for estimating response parameters using `gamma_start`. Otherwise default or user-supplied starting values will be used.
`start.seed`	Seeds for generating random starting values for response parameters.
`fit.control`	List of settings for the EM algorithm as returned by `em.control`.
`min.sac`	Minimum saccade duration (in s).

The algorithm consists of a preprocessing, classification, and postprocessing step.

During preprocessing, the raw data x and y are first converted into degrees of visual angle (only if unit was 'px'). Samples classified as blinks by blink and those surrounding them (by b.win) are set to NA.The remaining coordinates are then used to compute velocity, acceleration, and sample-to-sample angle signals. Velocity and acceleration are calculated by applying a Savitzky-Golay filter to the sampel coordinates and the sample-to-sample angle by apply finite forward and backward differences.

In the classification step, a hidden Markov model with velocity, acceleration, and sample-to-sample angle as dependent variables classifies each sample as belonging to one of nstates states. The model describes the velocity and acceleration signals by mixtures of gamma distributions with shape and scale parameters. Sample-to-sample angle is modeled by a mixture of von Mises distributions and a uniform distribution. The argument sf determines by which factor velocities and accelerations will be divided. Increasing the factor can improve the fitting of the model (although the default should usually suffice). If instart or trstart are not supplied, uniform starting values will be used (i.e., 1/nstates).

The postprocessing routine relabels samples that belong to one-sample fixations or smooth pursuits, saccades with a duration below min.sac, or PSOs following non-saccade samples. The respective samples are relabeled as the previous event.

The classification labels correspond to the following events:

0: Blink/noise
1: Fixation
2: Saccade
3: PSO
4: Smooth pursuit

A list object of class 'gazeHMM' containing four elements:

samples: Preprocessed gaze data with postprocessed sample labels.
events: A list with data frames for each classified event containing the event metrics (e.g., fixation duration).
model: The depmix.fitted model.
settings: The arguments of gazeHMM used to obtain results (for reproducibility).

data(video)

res <- c(1024, 768)
dim <- c(380, 300)
dist <- 670
fr <- 500

df <- video[video$subject == 1,]

res <- gazeHMM(x = df$x, y = df$y, t = df$t, unit = "px",
               res = res, dim = dim, dist = dist, fr = fr, blink = c(0, 0),
               nstates = 4, sf = c(100, 100), random.respstart = FALSE,
               min.sac = 0.01)