09-16-2022, 07:29 AM
When creating a smooth pursuit task it is a good idea to include pursuit target position information so that target and eye movements can be compared at the analysis stage. The Experiment Builder "Pursuit" demo (File > Examples > Pursuit), as well as our Pursuit demos for other experiment-creation software such as Psychtoolbox/Matlab and Psychopy show how target information can be saved for later use by our Data Viewer software.
The Experiment Builder Pursuit demo is described in detail in the manual (in Experiment Builder click on Help > Contents > Examples > Pursuit) while demos in other experiment-creation software have commented lines of code.
Creating target information for Data Viewer involves writing a "!V TARGET_POS TARG1..." message whenever your experiment draws the pursuit target at a new target position on the screen (e.g. at each screen refresh). Data Viewer is then able to output target position data as well as eye movement data at the sample level from 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 pursuit measures:
Smooth pursuit eye movements are slow and thus not picked up the EyeLink's saccade-picking algorithm but are identified as fixation events instead (see section 4 of your EyeLink's User Manual). The attached pursuitDV app therefore uses gaze position samples within fixation events only, and compares them with the corresponding pursuit target position in order to generate some pursuit measures for each "fixation" event.
1- Import one or multiple 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 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 and include at least the following variables in the report:
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
It is fine to include all available variables in the report instead, however this could make the resulting Sample report very big. Only the above variables are used by the pursutDV app but you can include more. Once you move the variables to the "Selected Variables" list, click "Next" and save the Data Viewer session (if prompted), choose where to save the report, then enter a Sample report name in the "File name" field and beside "Files of type:" click on the "All Files" drop-down and select "Text (Tab-Delimited)(*.txt)" instead of "Microsoft Excel File". Click the "Save" button to output the Sample report. Note that 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 linked to this post, click the field to choose a sample report to be processed, and click to choose a destination folder, then click on the "Process" button to process the file.
5- Each row of the resulting tab-delimited "*_processed.txt" text file represents a separate "fixation" identified by the Eyelink parser (i.e. a section of smooth pursuit eye movements if the eyes followed smoothly the moving target). It can be opened in Excel and will have 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 pursuitDV app will output separate pursuit measures for left and right eye i.e. there will be separate rows for EYE_USED = L and EYE_USED = R. The pursuitDV app can be used to analyse smooth pursuit to targets in any direction.
To use the app, click on this link: pursuitDV.exe or pursuitDV.app to download it, unzip it and double-click on pursuitDV.exe (for Windows) or pursuitDV.app (for macOS). The app should work on recent versions of Windows and macOS but has been tested only on the following operating systems:
- Windows 10 and 11
- macOS 12.6
The Experiment Builder Pursuit demo is described in detail in the manual (in Experiment Builder click on Help > Contents > Examples > Pursuit) while demos in other experiment-creation software have commented lines of code.
Creating target information for Data Viewer involves writing a "!V TARGET_POS TARG1..." message whenever your experiment draws the pursuit target at a new target position on the screen (e.g. at each screen refresh). Data Viewer is then able to output target position data as well as eye movement data at the sample level from 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 pursuit measures:
Smooth pursuit eye movements are slow and thus not picked up the EyeLink's saccade-picking algorithm but are identified as fixation events instead (see section 4 of your EyeLink's User Manual). The attached pursuitDV app therefore uses gaze position samples within fixation events only, and compares them with the corresponding pursuit target position in order to generate some pursuit measures for each "fixation" event.
1- Import one or multiple 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 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 and include at least the following variables in the report:
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
It is fine to include all available variables in the report instead, however this could make the resulting Sample report very big. Only the above variables are used by the pursutDV app but you can include more. Once you move the variables to the "Selected Variables" list, click "Next" and save the Data Viewer session (if prompted), choose where to save the report, then enter a Sample report name in the "File name" field and beside "Files of type:" click on the "All Files" drop-down and select "Text (Tab-Delimited)(*.txt)" instead of "Microsoft Excel File". Click the "Save" button to output the Sample report. Note that 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 linked to this post, click the field to choose a sample report to be processed, and click to choose a destination folder, then click on the "Process" button to process the file.
5- Each row of the resulting tab-delimited "*_processed.txt" text file represents a separate "fixation" identified by the Eyelink parser (i.e. a section of smooth pursuit eye movements if the eyes followed smoothly the moving target). It can be opened in Excel and will have 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 pursuitDV app will output separate pursuit measures for left and right eye i.e. there will be separate rows for EYE_USED = L and EYE_USED = R. The pursuitDV app can be used to analyse smooth pursuit to targets in any direction.
To use the app, click on this link: pursuitDV.exe or pursuitDV.app to download it, unzip it and double-click on pursuitDV.exe (for Windows) or pursuitDV.app (for macOS). The app should work on recent versions of Windows and macOS but has been tested only on the following operating systems:
- Windows 10 and 11
- macOS 12.6