NeuroWaves NYUAD Documentation Logo
0.1.0

Lab Overview

  • Lab Overview
  • General Policies
  • Processes
  • Publications
  • Collaborations
  • Links and contacts
  • Contributing

SQUID-MEG

  • Technology Overview
  • System specification
  • Main Applications
  • Training
  • Operational Protocol
  • MEG Session Checklist
  • Experiment design
  • Dashboards
  • Display and trigger timing

OPM-MEG

  • Technology Overview
  • System specification
  • Main Applications
  • Training
  • Operational Protocol
  • Experiment design
  • Dashboards

Experiments Gallery

  • Example Experiments
    • General demo scripts
    • Psychtoolbox
    • Psychopy
      • Experiment example (PsychoPy): EyeLink eye-tracking starter demo
      • Experiment example (PsychoPy): Face Inversion Task
      • Experiment Project: Language studies
      • Experiment example (PsychoPy): Masked Priming English
      • Experiments example 3 (PsychoPy): Triggering all channels on KIT
    • Presentation

Projects

  • Epilepsy project: NYUAD collaboration with Cleveland Clinic Abu Dhabi

DataHub

  • Datasets
  • Data Naming and Storing

Pipeline Gallery

  • Pipelines Overview
  • Pipelines Gallery

BESA Software

  • Epilepsy Project: BESA Data Processing Pipeline

Talks and Demos

  • MEG Course
  • Demonstrations
  • Talks and presentations

MEG Operations

  • Maintenance of MEG system
  • Emergency procedures

Glossary and API

  • Glossary
  • API documentation of MEG-Pipeline
NeuroWaves NYUAD Documentation
  • Experiment design
  • Experiment example (PsychoPy): EyeLink eye-tracking starter demo

Experiment example (PsychoPy): EyeLink eye-tracking starter demo

Author: Hadi Zaatiti, hadi.zaatiti@nyu.edu

Description

A single PsychoPy script to get started with the EyeLink eye tracker on the MEG stimulus computer. It calibrates the tracker, shows where the participant is looking in real time, and measures how accurate the calibration is, so a new user can check the whole eye-tracking chain before writing their own experiment.

It is built from SR Research’s official PsychoPy Coder examples (picture.py and GC_window.py, psychopy-eyelink 2.2.1.1), which are kept in the repository next to it, and uses the same calibration settings as the lab’s MATLAB/Psychtoolbox MGS eye-tracking task.

The script runs in three steps:

  1. Camera setup and calibration. The standard EyeLink setup screen opens on the participant screen. From the stimulus computer keyboard: ENTER shows or hides the camera image, C calibrates, V validates, ESC or O leaves the setup screen.

  2. Live gaze. A blue dot follows the eye and an orange line shows the path it took, either as a 1.5 s fading trail or as the full path since it was last cleared. Nine reference circles mark the calibration points: look at each one and check the dot lands on it.

  3. Accuracy check. Nine dots appear one at a time on the calibration points. For each dot the script takes the median gaze position and reports the error in degrees of visual angle, then shows a summary screen (green < 0.5°, yellow < 1°, red otherwise) with an overall GOOD / FAIR / POOR verdict. The experimenter can recalibrate and repeat from that screen.

The script also has a dummy mode in which the mouse plays the role of the eye, so it can be tried on any computer without the tracker. If the tracker cannot be reached, the script offers to continue in dummy mode.

Keys

Screen

Key

Action

Camera setup

ENTER

Show / hide the camera image

C / V

Calibrate / validate

ESC or O

Leave the setup screen

Live gaze

P

Switch between fading trail and full path

C

Clear the path

R

Recalibrate

SPACE

Go to the accuracy check

Accuracy summary

R

Recalibrate and repeat the check

SPACE

Finish

Anywhere

ESC

Stop the demo (the data is still saved)

Calibration settings

The calibration follows the lab’s MATLAB MGS task (mgs_meg_main...m):

  • HV9 calibration, with the calibration and validation points confined to the central 50% of the screen (calibration_area_proportion = 0.5 0.5) instead of the EyeLink default of about 88% × 83%.

  • Monocular tracking of the right eye (binocular_enabled = NO, active_eye = RIGHT), set before calibration, with EDF and link data filtered to the right eye.

  • Saccade parser thresholds of 35 °/s (velocity) and 9500 °/s² (acceleration).

  • Mid-grey calibration target (200/255) on a dark-grey background (100/255), 1% of the screen width.

  • Screen geometry used for the degree conversion: 65 cm wide screen, eyes 56.5 cm from the screen centre (the MEG-room measurements).

All of these are set at the top of the script:

# =============================================================================
TRACKER_IP = "100.1.1.1"     # default EyeLink Host PC address

SCREEN_INDEX = 1             # default screen for the participant display. The lab's other
                             # scripts use screen=1 for the stimulus/projector screen.
                             # The start dialog lists the detected screens so you can change it.
FULL_SCREEN = True           # set False while debugging
WINDOW_SIZE = (1280, 720)    # only used when FULL_SCREEN is False

# Physical display geometry, used to convert pixels to degrees in the accuracy
# check. Values are the MEG-room measurements from the lab's MATLAB MGS task
# (mgs_meg_main...m): 65 x 36.5 cm screen, eyes 56.5 cm from the screen centre.
SCREEN_WIDTH_CM = 65.0       # visible width of the image on the screen (cm)
VIEW_DISTANCE_CM = 56.5      # participant's eyes to screen centre (cm)

# Colours on a 0-255 scale, same as the MATLAB task
BACKGROUND_COLOR_255 = (100, 100, 100)   # dark grey background
CAL_TARGET_COLOR_255 = (200, 200, 200)   # mid-grey calibration target
CAL_TARGET_SIZE_PCT = 1.0                # target diameter, % of screen width

# Calibration: same settings as the MATLAB MGS task
CALIBRATION_TYPE = "HV9"     # 9 points (MATLAB task). HV5 quicker, HV13 more thorough
CALIBRATION_AREA = (0.5, 0.5)  # calibration/validation points span the central
                             # 50% of the screen width/height (EyeLink default is
                             # about 0.88 x 0.83). None = tracker default.
TRACKED_EYE = "RIGHT"        # monocular right eye, like the MATLAB task.
                             # "LEFT", "RIGHT", or None to keep the Host PC setting.
SACCADE_VELOCITY_THRESHOLD = 35        # deg/s  (conservative parser, as in MATLAB)
SACCADE_ACCELERATION_THRESHOLD = 9500  # deg/s^2
SAMPLE_RATE = None           # e.g. 1000. None = keep the Host PC setting.

TRAIL_SECONDS = 1.5          # length of the fading trail in live-gaze mode
MAX_PATH_POINTS = 3000       # cap for "full path" mode

# The live-gaze reference circles and the accuracy-check dots sit on the same
# 3x3 grid as the calibration points (set by CALIBRATION_AREA).
ACC_SETTLE_S = 0.8           # ignore gaze for this long after a target appears
ACC_COLLECT_S = 0.8          # then average gaze over this window
GOOD_DEG = 0.5               # SR Research rule of thumb: mean < 0.5 deg is good
OK_DEG = 1.0
# =============================================================================

Running the demo

  1. Install the dependencies, either PsychoPy Standalone with the EyeLink plugin (Tools > Plugins / packages manager), or a conda environment created from the environment.yml next to the script (conda env create -f environment.yml). It installs psychopy, psychopy-eyelink, psychopy-eyelink-coregraphics and sr-research-pylink.

  2. Turn on the EyeLink Host PC and make sure it is showing the EyeLink software. The stimulus computer’s tracker network port should be 100.1.1.2 / 255.255.255.0; the Host PC is 100.1.1.1.

  3. Run eyelink_gaze_demo.py (PsychoPy Coder or VS Code with the PsychoPy environment).

  4. In the start dialog, enter an EDF file name (8 characters max, letters / numbers / _), leave Dummy mode unticked, and choose the participant screen. The dialog lists every screen with its index, resolution and position; the default is screen 1, as in the lab’s other PsychoPy scripts.

Note

The EyeLink setup screen reads keys through the PsychoPy window. When the window opens full screen on the second (participant) screen it may not have keyboard focus, and ENTER / C then go to whatever window does (for example the VS Code terminal). The script gives the window focus when it opens, and the instruction screen before the setup screen reads SPACE the same way: if SPACE does nothing there, click once on the participant screen.

Output

Each run creates results/<EDFNAME>_<YYYY_MM_DD_HH_MM>/ next to the script, containing:

  • <id>.EDF: the full-rate EyeLink recording, copied from the Host PC when the demo exits. Open it in Data Viewer, or convert it with edf2asc and load it in MNE with mne.io.read_raw_eyelink("file.asc").

  • <id>_gaze_samples.csv: gaze during the live-gaze step, one row per screen frame (a convenient lower-rate copy; use the EDF for analysis).

  • <id>_accuracy_check.csv: target position, measured gaze and error for every accuracy-check dot.

The EDF contains messages that can be used as event markers, such as LIVE_GAZE_START / LIVE_GAZE_END, TARGET_ON <n> <x> <y>, TARGET_OFF <n> and ACCURACY_RESULT mean <m> max <m> deg.

The results/ folder is git-ignored so participant eye-tracking data does not end up in the repository.

Using it in your own experiment

All the tracker code is in the EyeLinkSession class of the script (connect, attach_window, calibrate, start_recording, get_gaze, message, close). Copy it into your experiment, send a message() at each stimulus onset alongside the MEG trigger, and call close() at the end to copy the EDF to the stimulus computer.

Code Access

EyeLink gaze demo script

Demo folder (script, README, environment.yml)

Official SR Research PsychoPy examples

References

  • SR Research: Getting started with PsychoPy

  • EyeLink Developers Kit

  • psychopy-eyelink on PyPI

Previous Next

© Copyright 2025, Hadi Zaatiti, Haidee Paterson, Osama Abdullah.

Built with Sphinx using a theme provided by Read the Docs.