adjust_times: Adjust looking times relative to some event

In tjmahr/littlelisteners: Helper Functions for Hand-coded Eyetracking Data

Adjust looking times relative to some event

Description

This function is useful if some critical event occurs each trial, and we would like to adjust the timestamps so that they are relative to that event time.

Usage

adjust_times(
  data,
  time_var = quote(Time),
  event_var = NULL,
  ...,
  align = TRUE,
  fps = 60,
  ties = "first"
)

Arguments

data	a long data frame of looking data
time_var	a column in data with looking times (assumed to be milliseconds).
event_var	a column in data with the time of some event
...	grouping variables. The grouping variables should uniquely specify a trial of eyetracking data.
align	whether to align the eyetracking times so that the frame closest to the event time gets time = 0.
fps	the eyetracking sampling rate. Defaults to 60 frames per second.
ties	how to break ties when the smallest times are equally close to zero. Default is "first" so that the tie c(-1, 1) is aligned to c(0, 2).

Value

the looking data with the times adjusted by event times. By default, these times are aligned so that the frame closest to the event time gets value 0.

Examples

# Consider some raw tims from an eyetrack. For each trial, some critical
# event occurs and we have a column with the time of that event for each
# trial.
trial1 <- data.frame(trial = 1, time_ms = 1:5, event = 2)
trial2 <- data.frame(trial = 2, time_ms = 6:10, event = 8.5)
trial_times <- dplyr::bind_rows(trial1, trial2)
trial_times

# We want to adjust the times so that time 0 is time of the critical event.
adjust_times(trial_times, time_ms, event, trial, fps = 1000)

# The times are adjusted so that the frame closest to the event time gets
# the time zero. Setting `align` to `FALSE` skips this behavior.
adjust_times(trial_times, time_ms, event, trial, align = FALSE, fps = 1000)

# In the second trial there is a tie. Two frames are equally close to 0. By
# default the first frame is chosen to be zero, but setting `ties` to
# `"last"` will break ties with the later frame.
adjust_times(trial_times, time_ms, event, trial, ties = "last", fps = 1000)

tjmahr/littlelisteners documentation built on July 31, 2024, 6:02 a.m.