PsychoPy is a Python-based stimulus presentation package. The PyLink library for Python, which is a fully-featured wrapper for the EyeLink C API, provides full support for EyeLink eye trackers in PsychoPy. 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 available API functions.
Programming in PsychoPy is accomplished either via a drag-and-drop, graphical Builder environment or via a Coder environment that allows you to view or edit the full Python code of your experiments.
Within the Builder, there are two options for interacting with EyeLink systems. First, you can use the EyeLink Plugin for PsychoPy, which provides a set of components for EyeLink integration. These components will appear in the Eyetracking section of the Components panel after the plugin is installed.
⚠️ Important: Please do not install the plugin called psychopy-eyetracker-sr-research. That is an older plugin that uses the built-in ioHub eye tracker extension for PsychoPy and does not provide full-featured EyeLink integration. Please make sure to install the plugin called psychopy-eyelink.
The second integration method within the Builder is to use Code components. This allows for more customized control by making direct calls to the PyLink module at specific moments in your experiment.
For those who prefer to work entirely in code, EyeLink integration within the Coder is achieved by calling the PyLink module directly from your Python script.
We provide example sets for each approach: using the EyeLink Plugin, using Builder with Code components, and using the Coder directly. Please see the links below.
A key advantage of PsychoPy is that any Builder experiment can be "compiled" into editable code for the Coder. This flexibility allows you to mix and match integration methods. For example, you can handle the main setup using the graphical EyeLink Plugin components, then add custom features with PyLink calls from a Code component or by modifying the compiled code directly.
Installation instructions
EyeLink Plugin for Psychopy
⚠️ Important: If you plan to use the EyeLink Plugin, you must also follow the additional setup steps described in section 1.3 of the EyeLink Plugin for PsychoPy User Manual.
EyeLinkPluginForPsychoPyUserManual_1.0.pdf (Size: 1.71 MB / Downloads: 1,048)
Templates / Example Experiments
We provide different example sets for each integration method.
Description of Examples
A detailed walkthrough for Coder integration, using the picture.py script as a starting point, is available in Section 5 of the Getting Started with Python and PyLink guide. The table below describes all the Coder examples provided with the EyeLink Developers Kit.
Updated Examples for PsychoPy 2024.1.0
PsychoPy 2023.2.0 introduced changes affecting the way the Builder creates .py files. Then, PsychoPy 2024.1.0 introduced changes to how PsychoPy handles user dialogs (like the EDF file dialog). As a result, there are separate example sets for different versions. Please make sure to download the appropriate example set for your version of PsychoPy.
Testing Your Installation
To test your installation, run one of the examples mentioned above for your intended integration method.
Open the script in PsychoPy's Coder view and click the "Run" button.
EyeLink Data Viewer Messaging Commands and Syntax
Throughout your experiment, in addition to sending messages to the EyeLink data file (EDF) to log event timing, it's a best practice to send special messages that allow for integration with EyeLink Data Viewer. If you use the EyeLink Plugin for PsychoPy, this is handled automatically. Alternatively, the Builder (Code Component method) and Coder examples included in the EyeLink Developers Kit illustrate how to manually send messages that convey important trial information, such as start/end times, variable values, and stimulus details. For detailed information on the messaging protocol, you can watch the EyeLink Data Viewer Integration webinar or consult the Data Viewer User Manual (via Help -> Contents) under the section "Protocol for EyeLink Data to Viewer Integration".
Documentation
To learn how to use the EyeLink Plugin for PsychoPy, please refer to the EyeLink Plugin for PsychoPy User Manual.
EyeLinkPluginForPsychoPyUserManual_1.0.pdf (Size: 1.71 MB / Downloads: 1,048)
For Coder integration, a video tutorial is available that provides an overview and a detailed walkthrough of the picture.py example. The PyLink API User Guide and the Getting Started with Python and PyLink guide contain the primary documentation; both are included with the EyeLink Developers Kit and are located in the SampleExperiments/Python/ directory.
For advanced users, the EyeLink Programmer's Guide provides complete documentation of the underlying C API. While the syntax differs from PyLink, the core functionality of the functions is analogous and can provide deeper insight.
Programming in PsychoPy is accomplished either via a drag-and-drop, graphical Builder environment or via a Coder environment that allows you to view or edit the full Python code of your experiments.
Within the Builder, there are two options for interacting with EyeLink systems. First, you can use the EyeLink Plugin for PsychoPy, which provides a set of components for EyeLink integration. These components will appear in the Eyetracking section of the Components panel after the plugin is installed.
⚠️ Important: Please do not install the plugin called psychopy-eyetracker-sr-research. That is an older plugin that uses the built-in ioHub eye tracker extension for PsychoPy and does not provide full-featured EyeLink integration. Please make sure to install the plugin called psychopy-eyelink.
The second integration method within the Builder is to use Code components. This allows for more customized control by making direct calls to the PyLink module at specific moments in your experiment.
For those who prefer to work entirely in code, EyeLink integration within the Coder is achieved by calling the PyLink module directly from your Python script.
We provide example sets for each approach: using the EyeLink Plugin, using Builder with Code components, and using the Coder directly. Please see the links below.
A key advantage of PsychoPy is that any Builder experiment can be "compiled" into editable code for the Coder. This flexibility allows you to mix and match integration methods. For example, you can handle the main setup using the graphical EyeLink Plugin components, then add custom features with PyLink calls from a Code component or by modifying the compiled code directly.
Installation instructions
- Configure your Display PC's network connection to communicate with the EyeLink Host PC.
- Download and install the latest version of the EyeLink Developers Kit.
- Download and install the latest version of latest version of PsychoPy.
- Update the PyLink library included in PsychoPy. The PyLink library packaged with PsychoPy may be older than the one included in the EyeLink Developers Kit. You can update it using one of the two methods below.
- Option A (Recommended): Update using PIP
The easiest method is to run a PIP command from PsychoPy's package manager. Navigate to Tools -> Plugins/Packages and open the PIP Terminal from the Packages tab. Then, run the following command:
Code:install sr-research-pylink --upgrade
Note: For versions of PsychoPy earlier than 2025.1.1, the command must include pip at the beginning: pip install sr-research-pylink --upgrade.
- Option B: Manually Replace the PyLink Folder
Alternatively, you can manually 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 into:
- macOS: Copy the pylink folder from /Applications/EyeLink/SampleExperiments/Python/3.8/ and paste it into the site-packages folder for your version of Python, which may be:
or
- Ubuntu: Enter the following command in the Terminal to copy the correct pylink folder to PsychoPy's packages directory. Use the command that matches the version of Python your PsychoPy installation is using:
orCode:sudo cp -r /usr/share/EyeLink/SampleExperiments/Python/64/3.8/pylink /usr/lib/python3/dist-packages/
Code:sudo cp -r /usr/share/EyeLink/SampleExperiments/Python/64/3.10/pylink /usr/lib/python3/dist-packages/
- Windows (64-bit): Copy the pylink folder from C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\Python\64\3.8\ and paste it into:
- Option A (Recommended): Update using PIP
- Verify the Installation
To check if PyLink is properly installed in PsychoPy, enter the following code in the PsychoPy Coder shell. If no error message appears, you are all set.
Code:import pylink
EyeLink Plugin for Psychopy
⚠️ Important: If you plan to use the EyeLink Plugin, you must also follow the additional setup steps described in section 1.3 of the EyeLink Plugin for PsychoPy User Manual.
EyeLinkPluginForPsychoPyUserManual_1.0.pdf (Size: 1.71 MB / Downloads: 1,048)
Templates / Example Experiments
We provide different example sets for each integration method.
- Examples for the EyeLink Plugin
Example projects are available for different integration methods. For the EyeLink Plugin, a dedicated example set can be downloaded below; a step-by-step walkthrough is included in Chapter 3 of the plugin's user manual.
EyeLinkPluginForPsychoPy_Examples.zip (Size: 3.46 MB / Downloads: 307)
- Examples for Builder (Code Components) & Coder
Examples for the Builder (using Code Components) and Coder methods are included with the EyeLink Developers Kit.
Examples for Psychopy's Coder can be found in teh following File locations after installing the EyeLink Developers Kit:- 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
If you are using the EyeLink Plugin for PsychoPy, you don't have to worry about this—the appropriate EyeLinkCoreGraphicsPsychoPy.py file will be installed along with the plugin.
- Windows: C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\Python\examples\Psychopy_examples
Description of Examples
A detailed walkthrough for Coder integration, using the picture.py script as a starting point, is available in Section 5 of the Getting Started with Python and PyLink guide. The table below describes all the Coder examples 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 |
Updated Examples for PsychoPy 2024.1.0
PsychoPy 2023.2.0 introduced changes affecting the way the Builder creates .py files. Then, PsychoPy 2024.1.0 introduced changes to how PsychoPy handles user dialogs (like the EDF file dialog). As a result, there are separate example sets for different versions. Please make sure to download the appropriate example set for your version of PsychoPy.
- Builder Examples:
PsychoPy_Builder_Examples_For_Versions_2024.1.0_And_Later.zip (Size: 3.95 MB / Downloads: 217)
PsychoPy_Builder_Examples_For_Versions_2023.2.x.zip (Size: 3.77 MB / Downloads: 49)
PsychoPy_Builder_Examples_For_Versions_2023.1.3_And_Earlier.zip (Size: 3.88 MB / Downloads: 156)
- Coder Examples:
There is a detailed, step-by-step walkthrough for Coder integration following the picture example 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:
The Coder examples have been updated
PsychoPy_Coder_Examples_For_Versions_2024.1.0_And_Later.zip (Size: 3.14 MB / Downloads: 159)
Testing Your Installation
To test your installation, run one of the examples mentioned above for your intended integration method.
Open the script in PsychoPy's Coder view and click the "Run" button.
EyeLink Data Viewer Messaging Commands and Syntax
Throughout your experiment, in addition to sending messages to the EyeLink data file (EDF) to log event timing, it's a best practice to send special messages that allow for integration with EyeLink Data Viewer. If you use the EyeLink Plugin for PsychoPy, this is handled automatically. Alternatively, the Builder (Code Component method) and Coder examples included in the EyeLink Developers Kit illustrate how to manually send messages that convey important trial information, such as start/end times, variable values, and stimulus details. For detailed information on the messaging protocol, you can watch the EyeLink Data Viewer Integration webinar or consult the Data Viewer User Manual (via Help -> Contents) under the section "Protocol for EyeLink Data to Viewer Integration".
Documentation
To learn how to use the EyeLink Plugin for PsychoPy, please refer to the EyeLink Plugin for PsychoPy User Manual.
EyeLinkPluginForPsychoPyUserManual_1.0.pdf (Size: 1.71 MB / Downloads: 1,048)
For Coder integration, a video tutorial is available that provides an overview and a detailed walkthrough of the picture.py example. The PyLink API User Guide and the Getting Started with Python and PyLink guide contain the primary documentation; both are included with the EyeLink Developers Kit and are located in the SampleExperiments/Python/ directory.
- Windows: C:/Program Files(x86)/SR Research/EyeLink/SampleExperiments/Python/
- Mac: /Applications/Eyelink/SampleExperiments/Python/
- Linux: /usr/share/EyeLink/SampleExperiments/Python/
For advanced users, the EyeLink Programmer's Guide provides complete documentation of the underlying C API. While the syntax differs from PyLink, the core functionality of the functions is analogous and can provide deeper insight.