eyelink-reader 0.2.0

A package to import eye tracking recording generated by SR Research Eyelink eye tracker from EDF-files.

eyelink_reader

eyelink_reader is a Python library to import eye tracking recording from EDF-files generated by SR Research EyeLink eye tracker. It includes options to import events and/or recorded samples and pasring of individual events such as saccades, fixations, blinks, recorded variables, triggers, and areas-of-interest. Please read documentation at eyelink-reader.readthedocs.io.

Installation

Please note that these instructions may be outdate, i.e., if SR Research changes its software. If that is the case, please raise an issue.

Install SR Research EyeLink Developers Kit

This package relies on edfapi library that is as part of the EyeLink Developers Kit, which can be downloaded from www.sr-research.com/support website. Note that you need to register and wait for your account to be activated. Next, follow instructions to install EyeLink Developers Kit for your platform. The forum thread should be under SR Support Forum › Downloads › EyeLink Developers Kit / API › Download: EyeLink Developers Kit / API Downloads (Windows, macOS, Linux).

Please note that this package will not work without Eyelink Developers Kit!

Specify location of the edfapi library

The package looks for edfapi either in the global environment (i.e., the folder is added to the PATH) or in a typical path for the OS. The typical locations are:

• For Windows: c:/Program Files (x86)/SR Research/EyeLink/libs/x64
• For Mac OSX: /Library/Frameworks
• For Linux: edpapi library is install in /usr/lib, so is in the global path.

If you installed EyeLink Developers Kit using defaults, the typical paths should work. However, you may have used a different folder for installation (relevant primarily for Windows) or it is possible that SR Research changed the defaults. In this case, you can specify path to the library as a parameter or set EDFAPI_LIB environment variable.

Install package via pip

pip install eyelink_reader

Usage

All the functionality in encapsulated in the EDFFile class. The minimal call that imports events but not samples and parses all possible events is

from eyelink_reader import EDFFile

gaze = EDFFile("test.edf")

Importing samples

To import samples with all fields use

gaze = EDFFile("test.edf", loadsamples=True)

In most cases, you probably only want a subset of fields, which you can specify via sample_fields parameter (for the list of fields see Samples). For example, you can only import sample time and eye position in screen coordinates, as shown below. For binocular fields, such as gx that are split into gxL and gxR in Samples table, you only need to specify the common name gx.

gaze = EDFFile("test.edf", loadsamples=True, sample_fields=["time", "gx", "gy"])

Specifying custom trial start and end messages

By default, the library assumes that trial start and end are marked by standard messages "TRIALID" and "TRIAL_RESULT", respectively. However, you can pass custom messages via start_marker_string and end_marker_string parameters.

gaze = EDFFile("test.edf", start_marker_string="TRIALID", end_marker_string="TRIAL_RESULT")

Verbose loading

For large files loading may take some seconds. If you want to monitor the process, you can enable a progress bar via verbose=True:

gaze = EDFFile("test.edf", loadsamples=True, verbose=True)

Specifying edfapi library path

As described in the section above, EDFFile searches for edfapi library in the global path, path in EDFAPI_LIB environtment library, and a typical path for the OS. However, you can also pass the path via libpath parameter:

gaze = EDFFile("test.edf", libpath="c:/Program Files (x86)/SR Research/EyeLink/libs/x64")

Parsing specific events

The events attrbiute of EDFFile is a table that contains all recorded events. For convenience, they can be parsed into

• saccades
• fixations
• blinks
• variables, see also Parsing variables section for details.
• triggers, see also Parsing triggers section for details.
• aois (areas-of-interest), see also Parsing AOIs section for details.

A specific set of events to be parsed and extract is specified via parse_events parameter. Use parse_events="all" to extract all event types (default behavior) and parse_events=None, if you do not want events to be parsed. If you only want a subset of events to be parse, pass their names as a list.

# does not parse any event
gaze = EDFFile("test.edf", parse_events=None)

# parses all events
gaze = EDFFile("test.edf", parse_events="all")

# also parses all events, as default is parse_events="all"
gaze = EDFFile("test.edf")


# also parses all events, as all are included in the list
gaze = EDFFile("test.edf",
    parse_events=("saccades", "fixations", "blinks", "variables", "triggers", "aois"))

# only extracts gaze events: saccades, fixations, and blinks
gaze = EDFFile("test.edf", parse_events=("saccades", "fixations", "blinks"))

Parsing variables

Trial variabels are recorded using messages in !V TRIAL_VAR <variable> <value> format. Note that value can contain white spaces, but variable name cannot. For example, message !V TRIAL_VAR Filename Face 01.png will be parsed into Filename="Face 01.png". If wide_variables=True (default), the library pivots table, so that each trial corrresponds to a single row with column trial and one column per variable. Note that the library does not attempt to guess column types, so all values are represented as strings. If wide_variables=False or there was an exception generated by pivot opeation, the table is in the long format with columns trial, variable, and value.

Parsing triggers

Triggers are custom messages with format <trigger-marker> <label>. The marker can be specified via trigger_marker parameter and its default value is "TRIGGER".

gaze = EDFFile("test.edf", trigger_marker="TRIGGER")

The label can contain white space but marker cannot, so the label for the message "TRIGGER Initial exposure" will be "Initial exposure". The triggers are stored in a table with columns trial, sttime, sttime_rel, and label, see also triggers output table.

Parsing AOIs

Rectangular areas of interest are described via a message with format "!V IAREA RECTANGLE <aoi_index> <left> <top> <right> <bottom> <label>", the label can contain white spaces. For output table details see areas-of-interest table.