Windowing Raw Sample Data
Austin Hurst
2026-02-22
# Import libraries required for the vignette
library(eyelinker)
library(dplyr)
library(stringr)
library(tidyr)
library(ggplot2)
In most situations, the raw sample data from the eye tracker isn’t
very useful on its own: generally, you’re interested in changes in eye
position and/or pupil size within certain periods of time
(e.g. change in pupil size following a stimulus onset).
To split the raw signals into segments based on task events we
typically need to extract and parse the message data, which contains
time-stamped messages sent by the experiment program during the
experiment runtime.
This vignette provides a basic example of how to extract events from
trial messages and align them with raw sample data.
# Read in example data
fpath <- system.file("extdata/mono250.asc.gz", package = "eyelinker")
asc <- read_asc(fpath)
Aligning Samples With Phases
Now that we’ve got a table of trial events and their onsets, all we
need to do is connect this info with the raw sample data.
For data recorded at 1000 Hz this is straightforward, but for 500 Hz
and 250 Hz recordings we need to do some extra work to make sure the
event timestamps line up properly with the sample timestamps. This is
because messages are always recorded at a resolution of 1000 Hz
regardless of the sampling frequency, meaning you can end up with
messages that happen in between samples instead of
corresponding directly to them (e.g. samples at times 10000, 10004,
10008, etc. and message at time 10002).
To fix this, let’s write a little utility function to sync message
timestamps to their nearest samples and use it on our table of
events:
sync_timestamps <- function(df, raw) {
# Get tracker sample rate and block onset timestamps from raw pupil data
ms_per_sample <- median(lead(raw$time)[1:10] - raw$time[1:10])
block_onsets <- raw %>%
group_by(block) %>%
summarize(onset = time[1])
# Adjust df so that its timestamps map onto the nearest sample timestamp
df <- df %>%
left_join(block_onsets, by = "block") %>%
group_by(block) %>%
mutate(
time = round((time - onset) / ms_per_sample) * ms_per_sample + onset
) %>%
select(-c(onset))
df
}
trial_phases <- sync_timestamps(trial_phases, asc$raw)
If you’re working with 1000 Hz recordings, you can skip the above
step completely.
Now that the event timestamps are properly aligned, let’s connect the
trial phases with the raw sample data!
rawdat <- asc$raw %>%
left_join(trial_phases, by = c("block", "time")) %>%
group_by(block) %>%
fill(phase, .direction = "down")
left_join here joins the the trial phases we defined
above to their corresponding blocks and timestamps in the raw gaze data.
Then, for each block we use fill to fill in the gaps
between trial events with the correct phase label.
Putting It Together
Now that we’ve identified the event phases for each sample in the raw
data, let’s try using it to help visualize the changes in pupil size
across trials.
First, we’ll drop all samples without a corresponding phase (all
samples prior to the trial onset message in this case) and get the time
relative to trial onset for each trial:
rawdat <- rawdat %>%
subset(!is.na(phase)) %>%
group_by(block) %>%
mutate(
trialtime = time - time[1]
)
Before we plot, let’s see what our data looks like now:
## # A tibble: 818 × 8
## # Groups: block [4]
## block time xp yp ps cr.info phase trialtime
## <dbl> <dbl> <dbl> <dbl> <dbl> <chr> <fct> <dbl>
## 1 1 5886021 511. 385. 1026 ... onset 0
## 2 1 5886025 510. 384. 1024 ... onset 4
## 3 1 5886029 511. 384. 1027 ... onset 8
## 4 1 5886033 511. 384. 1022 ... onset 12
## 5 1 5886037 511 384. 1020 ... onset 16
## 6 1 5886041 512. 385. 1019 ... onset 20
## 7 1 5886045 512. 386. 1013 ... onset 24
## 8 1 5886049 511. 386. 1017 ... onset 28
## 9 1 5886053 511 386. 1017 ... onset 32
## 10 1 5886057 511. 386. 1016 ... onset 36
## # ℹ 808 more rows
Now we can take the data and plot it out, color-coding by phase:
# Plot pupil size across the first 4 trials, color-coding by phase
ggplot(subset(rawdat, block < 5), aes(x = trialtime, y = ps, color = phase)) +
geom_line() +
facet_wrap(~ block) +
labs(color = "Phase") +
ylab("Pupil Size") +
xlab("Trial Time (ms)")
