How-To: Get smooth pursuit measures from Data Viewer

[kurt]

Saving Target Position Data for Pursuit Tasks
When creating a smooth pursuit task, we recommend including target position information. This allows for a direct comparison between target and eye movements during the analysis stage. The Experiment Builder "Pursuit" demo (File > Examples > Pursuit), as well as our Pursuit demos for other software (such as Psychtoolbox/Matlab and Psychopy), demonstrate how to save this information for use with our Data Viewer software.

The Experiment Builder Pursuit demo is described in detail in the Experiment Builder manual (in Experiment Builder, click Help > Contents > Examples > Pursuit). Demos in other experiment-creation software include commented lines of code for guidance.

Creating target information for Data Viewer involves writing a !V TARGET_POS TARG1... message whenever your experiment draws the pursuit target to a new position on the screen (e.g., at each screen refresh). Data Viewer can then output both target position and eye movement data at the sample level from the EDF files generated by these experiments (see the Data Viewer manual section "Protocol for EyeLink Data to Viewer Integration > Target Position").

---

Using the pursuitDV App to Generate Measures
Smooth pursuit eye movements are slow and thus are not picked up by the EyeLink's saccade-detection algorithm; instead, they are identified as fixation events (see section 4 of your EyeLink User Manual). The attached pursuitDV app, therefore, uses gaze position samples only from within these fixation events. It compares them with the corresponding pursuit target position to generate pursuit measures for each "fixation" event.

Analysis Steps

1. Import one or more smooth pursuit EDF files into a Data Viewer session.
   
2. Create an Interest Period in Data Viewer to isolate the section of each trial you are interested in (typically by using the messages that mark target onset/offset).
   
3. Output a Data Viewer Sample Report (Analysis > Reports > Sample Report) as a tab-delimited text file. Include at least the following variables:
   • DATA_FILE
     
   • LEFT_FIX_INDEX
     
   • LEFT_GAZE_X
     
   • LEFT_GAZE_Y
     
   • LEFT_VELOCITY_X
     
   • LEFT_VELOCITY_Y
     
   • RESOLUTION_X
     
   • RESOLUTION_Y
     
   • RIGHT_FIX_INDEX
     
   • RIGHT_GAZE_X
     
   • RIGHT_GAZE_Y
     
   • RIGHT_VELOCITY_X
     
   • RIGHT_VELOCITY_Y
     
   • TARGET_VELOCITY_X
     
   • TARGET_VELOCITY_Y
     
   • TARGET_X
     
   • TARGET_Y
     
   • TIMESTAMP
     
   • TRIAL_INDEX
     
   Note: While you can include all available variables, this may create a very large report. The pursuitDV app only uses the variables listed above, but including others is fine.
   
   To save the report: After moving the variables to the "Selected Variables" list, click Next. Save the Data Viewer session (if prompted) and choose a save location. Enter a name in the "File name" field. Beside "Files of type:", click the drop-down menu and select "Text (Tab-Delimited)(*.txt)". Click Save to output the report. (Note: The macOS version of Data Viewer does not have an option to save an Excel file.)
   
   
4. Once the Sample Report text file is saved, download and open the pursuitDV app. Click to choose the Sample Report to be processed, click to choose a destination folder, and then click the Process button.
   
   
5. Each row of the resulting tab-delimited *_processed.txt file represents a separate "fixation" identified by the EyeLink parser (i.e., a section of smooth pursuit, assuming the eyes smoothly followed the target). The file can be opened in Excel and will contain the following columns:
   • SESSION_LABEL (participant or EDF file name)
     
   • TRIAL_INDEX (sequential order of the trial in the recording)
     
   • EYE_USED (L for left or R for right)
     
   • FIX_INDEX (the sequential order of each "fixation" event in the trial)
     
   • START_EDF_TIME (EDF time at the start of the "fixation" event)
     
   • END_EDF_TIME (EDF time at the end of the "fixation" event)
     
   • DURATION (duration of the "fixation" event in milliseconds)
     
   • VEL_GAIN (pursuit velocity gain, calculated by dividing the average gaze angular velocity by the average target velocity during each "fixation" event)
     
   • RMSE_GAZE (root mean squared error, where the error is the Euclidean distance between target and gaze for every eye position sample within a "fixation" event)
     
   If the input file used for the pursuitDV app contains binocular eye movements, the app will output separate pursuit measures for the left and right eye (i.e., there will be separate rows where EYE_USED = L and EYE_USED = R). The pursuitDV app can be used to analyze smooth pursuit to targets moving in any direction.
   

---

Download and Installation
To use the app, click the appropriate link to download it:

• Windows: pursuitDV.exe (tested on Windows 10 and 11)
  
• macOS: pursuitDV.app (tested on macOS 12.6
  

Unzip the file and double-click the application to run it. The app should work on recent versions of Windows and macOS.