EyeLink Data
The EyeLink Host PC stores gaze data to an EDF (EyeLink Data Format) file, which is created on the Host PC at the start of an experiment. When the experiment finishes, the file is closed, and a copy is typically transferred via ethernet to the Display PC.
EDF files use a binary format and are immutable (read-only). This ensures data integrity by maintaining the gaze data exactly as it was recorded, before any post-hoc filtering. The copy on the Host PC serves as a backup, while the transferred copy is used for analysis.
Analysis Tools
EDF File Data Types
The image below shows an extract from an EDF file that has been converted to ASCII. It illustrates the three key EyeLink data types: Samples, Events, and Messages. Please note that all three data types are read into Data Viewer directly from the EDF File.
Samples:
Samples are the most fundamental data type. If sampling is set to 1000 Hz, one sample is recorded every millisecond. Sample data contains four critical columns (which appear as separate columns in the ASCII data):
In the extract above you can see that the timestamp increments by 2 with each row, indicating that the data was recorded at 500 Hz.
The highlighted sample that the person is fixating close to the center of a 1920x1080 screen. (Note: The X,Y data can be either "GAZE" (screen pixel coordinates), "HREF" or "RAW". HREF and RAW data are not appropriate for the vast majority of analysis scenarios, and will not be considered further here.)
The final column of ... is reserved for flags and is typically not useful for most analysis scenarios.
If the recording was binocular then the Gaze X, Gaze Y, and Pupil Size data appear for both eyes (left eye first, then right eye), as illustrated below. In this excerpt the timestamp increments by one for each sample, indicating that the data was recorded at 1000 Hz.
If the data was recorded in Remote Mode, the file will contain additional columns related to the location of the target sticker:
When converting EDF data to ASCII, you can choose to include three optional "sample level" data types:
When the eye cannot be tracked (for example during blinks) null values (".") are returned for the gaze X,Y data, and the Pupil Size data is zero.
Events
The Host PC parses gaze data in real-time as it is recorded, utilizing a "saccade picking" strategy to classify data into Fixations, Saccades, and Blinks. The start and end timestamps of each event are marked, with the "End" events providing detailed summary statistics (e.g., duration, average position).
Event Pairs Sequence The parsing strategy results in a predictable sequence of "Event Pairs":
For more information about the operation of the Host PC Parsing algorithm, please see section 4.3 of the user manual or the following thread:
How are saccades/fixations defined?
A list of each event type, and annotation of the End event summary data is provided below:
If Resolution data is output at the sample level in the converted ASCII data, it is also available in the ESACC and EFIX summary data.
Messages
Several types of messages appear in EDF files converted to ASCII. The file typically begins with system-generated messages, as illustrated below. While these messages are generally not required for statistical analysis, they contain potentially useful metadata, including:
For analysis purposes, the most critical messages are user-generated. These are typically sent by your stimulus presentation software to mark key experimental events, such as trial onset/offset, stimulus appearance, and participant responses.
Message Structure As illustrated below, these lines always begin with the MSG flag. The format consists of three parameters:
Note: Data Viewer automatically handles these offset calculations for you.
Messages that start with "!V" are special messages intended specifically for Data Viewer, our analysis software. These messages typically provide Data Viewer with information it needs such as the path to any image files (to use as a backdrop in Spatial Overlay View), interest area sets and information about trial variables (as illustrated below).
For a comprehensive discussion of Data Viewer Integration messages, please see section 7 of the and the following thread: [url=https://www.sr-research.com/support/thread-83.html]How-To: EyeLink Data Viewer Integration Messaging Protocol
The EyeLink Host PC stores gaze data to an EDF (EyeLink Data Format) file, which is created on the Host PC at the start of an experiment. When the experiment finishes, the file is closed, and a copy is typically transferred via ethernet to the Display PC.
EDF files use a binary format and are immutable (read-only). This ensures data integrity by maintaining the gaze data exactly as it was recorded, before any post-hoc filtering. The copy on the Host PC serves as a backup, while the transferred copy is used for analysis.
Analysis Tools
- Data Viewer: The optimal strategy for most scenarios is to import EDF files directly into Data Viewer. This software allows for visualization and report generation without manual conversion. (See Getting Started with Data Viewer for details).
- EDF2ASC: For specific needs, EDF files can be converted to ASCII text using the command line or GUI versions of the EDF2ASC tool. While useful for understanding file structure, this conversion is rarely necessary for standard analysis.
EDF File Data Types
The image below shows an extract from an EDF file that has been converted to ASCII. It illustrates the three key EyeLink data types: Samples, Events, and Messages. Please note that all three data types are read into Data Viewer directly from the EDF File.
Samples:
Samples are the most fundamental data type. If sampling is set to 1000 Hz, one sample is recorded every millisecond. Sample data contains four critical columns (which appear as separate columns in the ASCII data):
- Timestamp: "EDF Time"/"Tracker Time" based on the Host PC clock (starts at 0 when the Host is turned on).
- Gaze X: Screen pixel coordinate.
- Gaze Y: Screen pixel coordinate.
- Pupil Size: Recorded in arbitrary units (see How can I convert Pupil Size to mm? detailed information on how these units can be converted to mm.).
In the extract above you can see that the timestamp increments by 2 with each row, indicating that the data was recorded at 500 Hz.
The highlighted sample that the person is fixating close to the center of a 1920x1080 screen. (Note: The X,Y data can be either "GAZE" (screen pixel coordinates), "HREF" or "RAW". HREF and RAW data are not appropriate for the vast majority of analysis scenarios, and will not be considered further here.)
The final column of ... is reserved for flags and is typically not useful for most analysis scenarios.
If the recording was binocular then the Gaze X, Gaze Y, and Pupil Size data appear for both eyes (left eye first, then right eye), as illustrated below. In this excerpt the timestamp increments by one for each sample, indicating that the data was recorded at 1000 Hz.
If the data was recorded in Remote Mode, the file will contain additional columns related to the location of the target sticker:
- Target X/Y: The location of the target sticker in camera sensor pixels.
- Target Distance: The distance of the target sticker from the camera in millimeters (mm).). The excerpt below illustrates data for a monocular remote mode recording:
When converting EDF data to ASCII, you can choose to include three optional "sample level" data types:
- Velocity: The instantaneous velocity of the eye movement.
- Resolution: The spatial resolution of the data, expressed in pixels per degree.
- Input: The decimal value of the Status or Data pins on the Host PC Parallel Port (if equipped).
When the eye cannot be tracked (for example during blinks) null values (".") are returned for the gaze X,Y data, and the Pupil Size data is zero.
Events
The Host PC parses gaze data in real-time as it is recorded, utilizing a "saccade picking" strategy to classify data into Fixations, Saccades, and Blinks. The start and end timestamps of each event are marked, with the "End" events providing detailed summary statistics (e.g., duration, average position).
Event Pairs Sequence The parsing strategy results in a predictable sequence of "Event Pairs":
- EFIX (End Fixation) events always precede an SSAC (Start Saccade) event.
- ESAC (End Saccade) events always precede an SFIX (Start Fixation) event.
For more information about the operation of the Host PC Parsing algorithm, please see section 4.3 of the user manual or the following thread:
How are saccades/fixations defined?
A list of each event type, and annotation of the End event summary data is provided below:
If Resolution data is output at the sample level in the converted ASCII data, it is also available in the ESACC and EFIX summary data.
Messages
Several types of messages appear in EDF files converted to ASCII. The file typically begins with system-generated messages, as illustrated below. While these messages are generally not required for statistical analysis, they contain potentially useful metadata, including:
- Session Information: The specific date and time the session took place.
- Calibration/Validation: Detailed results of the calibration and validation procedures, including error values.
- System Info: Information about the Host PC configuration.
For analysis purposes, the most critical messages are user-generated. These are typically sent by your stimulus presentation software to mark key experimental events, such as trial onset/offset, stimulus appearance, and participant responses.
Message Structure As illustrated below, these lines always begin with the MSG flag. The format consists of three parameters:
- Timestamp: The time the message was logged.
- Offset: An optional integer value representing a delay (in milliseconds).
- Message Text: The content of the message itself.
Note: Data Viewer automatically handles these offset calculations for you.
Messages that start with "!V" are special messages intended specifically for Data Viewer, our analysis software. These messages typically provide Data Viewer with information it needs such as the path to any image files (to use as a backdrop in Spatial Overlay View), interest area sets and information about trial variables (as illustrated below).
For a comprehensive discussion of Data Viewer Integration messages, please see section 7 of the and the following thread: [url=https://www.sr-research.com/support/thread-83.html]How-To: EyeLink Data Viewer Integration Messaging Protocol