# Understanding the eyelinker Data Structure

#### 2019-09-22

After you’ve imported your ASC into R, you might find yourself trying to make sense of the resulting data. This vignettes walks you through the basic structure of the read.asc() output, and explains the different possible columns in each data frame along with any other relevant information.

## The Basic Structure

require(eyelinker)

# Load in an example file, look at structure
ascfile <- system.file("extdata/mono2000.asc.gz", package = "eyelinker")
str(asc, max.level = 1)
## List of 8
##  $raw :Classes 'tbl_df', 'tbl' and 'data.frame': 8976 obs. of 6 variables: ##$ sacc  :Classes 'tbl_df', 'tbl' and 'data.frame':  9 obs. of  11 variables:
##  $fix :Classes 'tbl_df', 'tbl' and 'data.frame': 13 obs. of 8 variables: ##$ blinks:Classes 'tbl_df', 'tbl' and 'data.frame':  0 obs. of  5 variables:
##  $msg :Classes 'tbl_df', 'tbl' and 'data.frame': 32 obs. of 3 variables: ##$ input :Classes 'tbl_df', 'tbl' and 'data.frame':  8 obs. of  3 variables:
##  $button:Classes 'tbl_df', 'tbl' and 'data.frame': 0 obs. of 4 variables: ##$ info  :'data.frame':  1 obs. of  20 variables:

The output format of read.asc() is a named list containing several data frames, each containing a different kind of data extracted from the ASC file. The names and contents of this list are as follows:

Name Data Frame Contents
raw Raw sample data containing gaze, pupil size, and (often) more
sacc Saccade end events
fix Fixation end events
blinks Blink end events
msg Messages sent to/from the tracker during recording
input Input port (TTL) events
button Button box / gamepad events
info Tracker hardware / setup / recording information

Apart from info, all data frames in the list are tibbles. We’ll discuss each of these data frames and the meanings of their columns/contents in greater detail below.

## Raw Sample Data

Raw sample data contains millisecond-by-millisecond eye data across the session, at the sample rate used for recording (anywhere from 125 Hz / 8 ms per sample to 2000 Hz / 0.5 ms per sample). Given the high temporal resolution of this data, this data frame can be very large and contain millions of rows.

The contents of this data frame can also vary quite a bit between files, depending on the recording settings (mount type, monocular vs binocular, CR tracking vs pupil only) and EDF to ASC conversion settings (including velocity/resolution/input/button data in output). The following is a comprehensive list of the possible (supported) raw column types and their meanings:

Column Description
block Block number that sample occurred in
time Timestamp of sample (in msec)
xp, xpl, xpr X position of (left/right) eye
yp, ypl, ypr Y position of (left/right) eye
ps, psl, psr Pupil size of (left/right) eye
xv, xvl, xvr X-axis velocity of (left/right) eye
yv, yvl, yvr Y-axis velocity of (left/right) eye
xr X resolution (in pixels per degree [see Footnote 1])
yr Y resolution (in pixels per degree [see Footnote 1])
input Input port value at time of sample
buttons Button box state at time of sample
cr.info Corneal reflection diagnostic/warning info
tx X-position of target sticker relative to camera
ty Y-position of target sticker relative to camera
td Distance of target sticker relative to camera (in mm)
remote.info Target tracking diagnostic/warning info

All ASC files contain timestamp, X/Y position, and pupil size columns. If both eyes are tracked in a given ASC, it will have separate position, pupil size, and (if present) velocity columns for both eyes, with the relevant eye indicated by the suffix “l” (for left eye) and “r” (for right eye) at the end of the column name. If corneal reflection tracking is used for recording (optional on EyeLink II, always used for EyeLink 1000 and newer), a cr.info column will also be present.

Velocity, resolution, input, and button data are not usually included in ASC files, but can be included if enabled in the EDFConverter/edf2asc export settings. If the data was recorded in remote mode (i.e using a target sticker to track head movements), the sample data may also contain columns indicating the position (tx, ty), distance from camera (td), and target tracking warning/diagnostic info (remote.info).

Information on how to interpret the contents of the cr.info and remote.info columns is available in the EyeLink 1000 Plus user’s guide (also applies to other EyeLink models), but in general anything other than a string of all .s indicates a warning or error regarding tracking for that sample.

Saccade events, as parsed by the EyeLink during recording, are also recorded in ASC files. The saccade data frame can contain the following columns:

Column Description
block Number of block that saccade occurred in
stime Saccade start time (in msec)
etime Saccade end time (in msec)
dur Saccade duration (in msec)
sxp X-coordinate of saccade start
syp Y-coordinate of saccade start
exp X-coordinate of saccade end
eyp Y-coordinate of saccade end
ampl Amplitude of saccade (in degrees of visual angle)
pv Peak velocity of saccade
xr X resolution (in pixels per degree [see footnote 1])
yr Y resolution (in pixels per degree [see footnote 1])
eye Eye that made the saccade (L or R)

Resolution columns (xr/yr) are only included in the saccade data if the ASC file is exported with resolution info enabled. If events are recorded in HREF format, saccade events contain start/end coordinates, amplitude, and peak velocity columns twice: once in HREF units and once in gaze (screen coordinates) units. Although both amplitude columns (href.ampl and ampl) are seemingly both in units of degrees, but their values differ slightly and are presumably calculated differently. Peak velocities (href.pv and pv), however, appear to be identical throughout.

## Fixation Events

Along with saccades, the EyeLink also parses fixation events during recording, which are also included in the ASC file. The fixation data frame can contain the following columns:

Column Description
block Number of block that fixation occurred in
stime Fixation start time (in msec)
etime Fixation end time (in msec)
dur Fixation duration (in msec)
axp Average X position during fixation
ayp Average Y position during fixation
aps Average pupil size during fixation
xr X resolution (in pixels per degree [see footnote 1])
yr Y resolution (in pixels per degree [see footnote 1])
eye Eye that made the fixation (L or R)

As with saccades, the resolution columns (xr/yr) are only included in the data frame if the ASC file is exported with resolution info enabled. If events are recorded in HREF format, fixation events contain average gaze coordinates and average pupil size columns twice: once in HREF units and once in gaze (screen coordinates) units. Because pupil size is computed the same way regardless of gaze units, the href.aps and aps columns will always be identical.

## Message Events

The message events data frame contains both messages from the tracker itself (e.g. messages about drift corrects and recording settings) and messages sent to the tracker during recording by the experiment program (e.g. the block/trial number, markers of events within the trial, etc.). read.asc() makes no attempt to parse message content, leaving this task to the user.

Column Description
block Number of block that message occurred in
time Message onset time (in msec)
text String containing the given message

## Input Events

Input events occur when digital input is received by the tracker’s parallel port. As such, only ASC files for experiments involving input to this port will contain any input events. Here is the structure of the input event data frame:

Column Description
block Number of block that input occurred in
time Input onset time (in msec)
value Value of input event

## Button Events

Button events occur when a button is pressed or released on a button box connected to the EyeLink. As such, only ASC files for experiments where a tracker-connected button box was used will contain any button events. Here is the structure of button event data frame:

Column Description
block Number of block that button press occurred in
time Button onset time (in msec)
button Number of button pressed (1 to 8)
state State of button (1 = pressed, 0 = released)

NOTE: Although support for button events has been implementing according to the info in the EyeLink 1000 User’s Manual, eyelinker has not officially been tested with any ASC files containing button events. If you encounter any issues importing files with button events, please send the maintainer an email or file an issue on the project’s GitHub page.

## Tracker/File Info

The info data frame consists of a single row containing information about the tracker setup, recording settings, and other useful metadata. Here is a table explaining the different info columns and their contents:

Column Description
date Date and time of recording
model EyeLink tracker model (e.g. EyeLink II, EyeLink 1000)
version EyeLink software version number
sample.rate Sample rate of recording (in Hz)
cr Whether corneal reflection tracking used (TRUE/FALSE)
left Whether left eye tracked (TRUE/FALSE)
right Whether right eye tracked (TRUE/FALSE)
mono Whether recording is monocular (TRUE) or binocular (FALSE)
screen.x X resolution of Stimulus PC display
screen.y Y resolution of Stimulus PC display
mount The mounting setup of the EyeLink (e.g. “Desktop / Monocular / Remote”)
filter.level The level of filtering applied to samples (0 = off, 1 = standard, 2 = extra)
sample.dtype Type of sample data (GAZE, HREF, or PUPIL)
event.dtype Type of event data (GAZE or HREF)
pupil.dtype Type of pupil size data (AREA or DIAMETER)
velocity Whether samples contains velocity data (TRUE/FALSE)
resolution Whether samples and events contain resolution data (TRUE/FALSE)
htarg Whether samples contain remote-mode head target data (TRUE/FALSE)
input Whether samples contain input data (TRUE/FALSE)
buttons Whether samples contain button data (TRUE/FALSE)

Some of the above information is not always available in an ASC file (e.g. screen resolution is not always present, mount type only applies to certain EyeLink models). If a given field of information is missing from the file, that column will contain an NA instead of another value.

### Date & Time

Date and time are dependent on the EyeLink’s internal clock, and thus may be way off considering these machines usually aren’t connected to the internet, people usually don’t bother to set date/time correctly in BIOS, and the motherboard clock batteries on some older EyeLink I/IIs are probably dead or dying.

### Screen Resolution

Sometimes the listed screen resolution X/Y values will be one pixel more than their actual values (e.g. 1025 x 769 instead of 1024 x 768). This isn’t an error: because the coordinates of the top-right corner of the screen are (0, 0) and not (1, 1), if you set the bottom-left coordinates to (1024, 768) the screen size (as far as the EyeLink knows) is 1025 pixels wide and 769 pixels tall. To avoid this problem, subtract 1 from the X/Y values when sending the screen resolution to the EyeLink in your experiment code (e.g. DISPLAY_COORDS 0 0 1023 767).

### Sample & Event Data Types

The sample.dtype and event.dtype fields indicate the position units used for samples and events, respectively (they can be different). All of the different possible position unit types (and their use cases) are explained detail in the EyeLink User’s Manual, but here’s a brief explanation of all three:

Unit Explanation
GAZE Pixel coordinates on the stimulus display that the participant is looking at
HREF Angles of eye rotation relative to the head
PUPIL Raw pupil coordinates relative to the EyeLink camera

For most use cases, you’ll want to be recording GAZE data (the default setting for both events and samples).

## Footnotes

1. The EyeLink 1000 Plus User’s Guide lists the units for the xr/yr resolution columns as being “position units per degree”, but based on the inspection of actual .asc files the X/Y resolution always appears to be in pixels per degree regardless of whether events are recorded in Gaze or HREF format.`