06-25-2021, 05:46 AM
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
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:
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. Then, PsychoPy 2024.1.0 introduced changes to the way PsychoPy handles user dialogs (like the EDF file dialog). So, there are separate sets for use with versions 2023.1.3 and earlier, for versions 2023.2.x, and for 2024.1.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:
PsychoPy_Builder_Examples_For_Versions_2024.1.0_And_Later.zip (Size: 3.65 MB / Downloads: 69)
PsychoPy_Builder_Examples_For_Versions_2023.2.x.zip (Size: 3.77 MB / Downloads: 8)
PsychoPy_Builder_Examples_For_Versions_2023.1.3_And_Earlier.zip (Size: 3.88 MB / Downloads: 105)
If you are using Coder, the user dialog changes introduced in 2024.1.0 required our examples to be edited (e.g., to handled the EDF file dialog). You can find a Coder example set for 2024.1.0 and up at the link below:
PsychoPy_Coder_Examples_For_Versions_2024.1.0_And_Later.zip (Size: 3.57 MB / Downloads: 59)
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:
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:
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:
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 PsychoPy
- 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/
or
/Applications/PsychoPy.app/Contents/Resources/lib/python3.10/
- Ubuntu: To move the correct pylink folder to PsychoPy enter the following code in terminal:
sudo cp -r /usr/share/EyeLink/SampleExperiments/Python/64/3.8/pylink /usr/lib/python3/dist-packages/or
sudo cp -r /usr/share/EyeLink/SampleExperiments/Python/64/3.10/pylink /usr/lib/python3/dist-packages/(depending on the version of Python your PsychoPy is using)
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.import pylink
- Windows (64-bit): Copy the pylink folder from C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\Python\64\3.8\ and paste it to:
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. Then, PsychoPy 2024.1.0 introduced changes to the way PsychoPy handles user dialogs (like the EDF file dialog). So, there are separate sets for use with versions 2023.1.3 and earlier, for versions 2023.2.x, and for 2024.1.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:
PsychoPy_Builder_Examples_For_Versions_2024.1.0_And_Later.zip (Size: 3.65 MB / Downloads: 69)
PsychoPy_Builder_Examples_For_Versions_2023.2.x.zip (Size: 3.77 MB / Downloads: 8)
PsychoPy_Builder_Examples_For_Versions_2023.1.3_And_Earlier.zip (Size: 3.88 MB / Downloads: 105)
If you are using Coder, the user dialog changes introduced in 2024.1.0 required our examples to be edited (e.g., to handled the EDF file dialog). You can find a Coder example set for 2024.1.0 and up at the link below:
PsychoPy_Coder_Examples_For_Versions_2024.1.0_And_Later.zip (Size: 3.57 MB / Downloads: 59)
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
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/