Getting Started with PsychoPy / EyeLink Integration
#1
PsychoPy is a Python based stimulus presentation solution. It comes with native support for EyeLink eye trackers, and contains a fully featured wrapper for the EyeLink C API via the PyLink library. In order to use PyLink with PsychoPy the EyeLink Developers Kit must be installed on the same computer as PsychoPy. Once the EyeLink Developers Kit is installed you should have full access to all of the available API functions.


Installation instructions
  1. Configure your Display PC's network connection to communicate with the EyeLink Host PC.
  2. Download and install the latest version of the EyeLink Developers Kit
  3. Download and install the latest version of PsychoPy
  4. Replace the PyLink library included in PsychoPy with the latest version. The PyLink library included in PsychoPy may be slightly older than the ones included in the EyeLink Developers Kit.  To be sure that you have the most up to date version, please replace the pylink folder that comes with PsychoPy with the appropriate version from the EyeLink Developers Kit.
    • Windows (64-bit): Copy the pylink folder from C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\Python\64\3.8\ and paste it to:

      C:\Program Files\PsychoPy\Lib\site-packages\

    • MacOS: Copy the pylink folder from /Applications/EyeLink/SampleExperiments/Python/3.8/ and paste it to:

      /Applications/PsychoPy.app/Contents/Resources/lib/python3.8/

    • Ubuntu: To move the correct pylink folder to PsychoPy enter the following code in terminal:

      Code:
      sudo cp -r /usr/share/EyeLink/SampleExperiments/Python/64/3.8/pylink /usr/lib/python3/dist-packages/
    To check if PyLink is properly installed in PsychoPy, enter the following code in the PsychoPy Coder shell. If no error message comes up, you are all set.

    Code:
    import pylink



Templates / Example Experiments

The EyeLink Developers Kit provides a number of example scripts that illustrate how to communicate with EyeLink eye trackers via PsychoPy. The example scripts can be found in the following locations:
  • Windows:           C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\Python\examples\Psychopy_examples
  • macOS:               /Applications/Eyelink/SampleExperiments/Python/examples/Psychopy_examples
  • Linux:                  /usr/share/EyeLink/SampleExperiments/Python/examples/Psychopy_examples

We have also created an equivalent set of PsychoPy example templates which use the Builder interface (rather than the Coder interface).  PsychoPy 2023.2.0 introduced changes affecting the way the Builder creates py files, so there are separate sets for use with versions 2023.1.3 and earlier and for versions 2023.2.0 and later.  Please make sure to get the appropriate example set for the version of PsychoPy you are using.  These templates can be downloaded from the links below:

.zip   PsychoPy_Builder_Examples_For_Versions_2023.2.0_And_Later.zip (Size: 3.77 MB / Downloads: 140)

.zip   PsychoPy_Builder_Examples_For_Versions_2023.1.3_And_Earlier.zip (Size: 3.88 MB / Downloads: 53)

To test your installation please run the picture.py coder example script described below. Open the script in PsychoPy's coder window, and click the run button.

   

There is a detail step-by-step walkthrough of the picture in Section 5 of the Getting Started with Python and Pylink guide (see below for the location of the PDF).

The following table lists all the example scripts that is provided with the EyeLink Developers Kit:
 
 
Template Description
picture This is a basic example, which shows how to connect to and disconnect from the tracker, how to open and close data files, how to start / stop recording, and the standard messages for integration with the Data Viewer software. We show four pictures one-by-one on each trial, and a trial terminates upon a keypress response or until 3 secs have elapsed.
pursuit This example script shows how to record the target position in a smooth pursuit task. This script also shows how to record dynamic interest area and target position information to the EDF data file so Data Viewer can recreate the interest area and playback the target movement.
saccade This example script shows how to retrieve eye events (saccades) during testing. A visual target appears on the left side, or right side of the screen and the participant is required to quickly shift gaze to look at the target (pro-saccade) or a mirror location on the opposite side of the central fixation (anti-saccade).
fixationWindow_fastSamples This is a basic example, which shows how to implement a gaze-based trigger. First a fixation cross is shown at the center of the screen. The trial moves on only when gaze has been directed to the fixation cross.
GC_window This script shows how to manipulate visual stimuli based on real-time gaze data. A mask is shown at the current gaze position in the "mask" condition; in the "window" condition, the image is masked, and a window at the current gaze position will reveal the image hidden behind the mask.
MRI_demo This is a basic example illustrating how to do continuous eye tracker recording through a block of trials (e.g., in an MRI setup), and how to synchronize the presentation of trials with a sync signal from the MRI. With a long recording, we start and stop recording at the beginning and end of a testing session (run), rather than at the beginning and end of each experimental trial. We still send the TRIALID and TRIAL_RESULT messages to the tracker, and Data Viewer will still be able to segment the long recording into small segments (trials).
video A simple video demo. In each trial eye movements are recorded while a video stimulus is presented on the screen.  Integration messages allow the video to play back in Data Viewer

EyeLinkCoreGraphicsPsychoPy.py
Each of the example scripts contains an additional script named EyeLinkCoreGraphicsPsychoPy.py. It contains a set of callback functions for tracker calibration an drift-correction etc. These functions have been implemented with native PsychoPy functions, and they are called by the EyeLink API to draw the calibration targets at appropriate locations. When developing your own tasks in PsychoPy it is important that you include this library with your experimental script, as per the example scripts.

EyeLink Data Viewer Messaging Commands and Syntax
Throughout the course of your experiment, in addition to sending messages to the EyeLink data file (i.e., EDF file) that log the timing of events within your task, it's typically a good idea to send special messages that allow integration with Data Viewer. The examples included in the EyeLink Developers Kit illustrate how to send special messages to the EDF to convey important information to Data Viewer, like trial starting/ending times, trial variable values, trial stimulus information, and more. You can find a webinar at the following link that covers the formatting of these messages in detail:
  • EyeLink Data Viewer Integration Messaging Protocol
You can also find full documentation of the protocol in the Data Viewer User Manual (Help -> Contents) under the section "Protocol for EyeLink Data to Viewer Integration".


Documentation
This video tutorial provides an overview of the basics of integrating EyeLink systems via PsychoPy, and a detailed walkthrough of the picture.py template

EyeLink / PsychoPy Integration Video Tutorial

PsychoPy uses the PyLink wrapper of the EyeLink Developers Kit: PyLink is fully featured and all of its functions are documented in the PyLink API User Guide which is packaged with the EyeLink Developers Kit. A very useful Getting Started with Python and PyLink PDF file can also be found in the same locations:
  • Windows:           C:/Program Files(x86)/SR Research/EyeLink/SampleExperiments/Python/
  • Mac:                    /Applications/Eyelink/SampleExperiments/Python/
  • Linux:                  /usr/share/EyeLink/SampleExperiments/Python/
Given that PyLink is a wrapper for our C API contained within the EyeLink Developers Kit, you may also find the EyeLink Programmer's Guide helpful in expanding your knowledge of given functions in the API. This document contains the complete documentation of our C API functions, data structure, and implementation. The syntax functions listed in the manual will likely differ in how they are wrapped within the PyLink library, but much of the functionality should be analogous.