Adjust looking times relative to some event — adjust

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
#>    trial time_ms event
#> 1      1       1   2.0
#> 2      1       2   2.0
#> 3      1       3   2.0
#> 4      1       4   2.0
#> 5      1       5   2.0
#> 6      2       6   8.5
#> 7      2       7   8.5
#> 8      2       8   8.5
#> 9      2       9   8.5
#> 10     2      10   8.5

# 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)
#> # A tibble: 10 × 3
#>    trial time_ms event
#>    <dbl>   <dbl> <dbl>
#>  1     1      -1   2  
#>  2     1       0   2  
#>  3     1       1   2  
#>  4     1       2   2  
#>  5     1       3   2  
#>  6     2      -2   8.5
#>  7     2      -1   8.5
#>  8     2       0   8.5
#>  9     2       1   8.5
#> 10     2       2   8.5

# 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)
#>    trial time_ms event
#> 1      1    -1.0   2.0
#> 2      1     0.0   2.0
#> 3      1     1.0   2.0
#> 4      1     2.0   2.0
#> 5      1     3.0   2.0
#> 6      2    -2.5   8.5
#> 7      2    -1.5   8.5
#> 8      2    -0.5   8.5
#> 9      2     0.5   8.5
#> 10     2     1.5   8.5

# 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)
#> # A tibble: 10 × 3
#>    trial time_ms event
#>    <dbl>   <dbl> <dbl>
#>  1     1      -1   2  
#>  2     1       0   2  
#>  3     1       1   2  
#>  4     1       2   2  
#>  5     1       3   2  
#>  6     2      -3   8.5
#>  7     2      -2   8.5
#>  8     2      -1   8.5
#>  9     2       0   8.5
#> 10     2       1   8.5