Getting Started: Analysing Smooth Pursuit Data in R

[Sam]

The attached R Script calculates basic smooth pursuit metrics using a Sample Report exported from Data Viewer. The script requires target position data to function. Ensure your experiment sends target position messages to the EDF file. Please refer to Section 7.3.7 of the Data Viewer User Manual for details on how to send target position messages from your stimulus presentation script.

If your target moves at a constant velocity, you do not need sample-by-sample target data. Instead, you can manually assign a constant value to the target_v variable in the script's main PursuitCalc functions.

The parsing algorithm on the EyeLink Host PC does not natively distinguish between fixations and smooth pursuit. Therefore, this script treats every "Fixation" event as a candidate "Pursuit Segment" and computes metrics for the data samples within that segment (there are separate functions for the  X and Y dimensions). The script loops through all trials and participants to output the following metrics for each segment:

• Length: The number of samples in the segment (equivalent to milliseconds if recording at 1000Hz) can be used to Filter out short segments and weight averages for Gain/RMSE. Summing these values yields the total pursuit duration.
  
• Velocity Gain: The average ratio of eye velocity to target velocity (Eye Velocity / Target Velocity). Low values (e.g., < 0.5) are unlikely to represent genuine pursuit and can be excluded.
  
• RMSE (Root Mean Square Error): The average spatial offset between the eye and the target, measured in degrees of visual angle.
  

To use the R script:

1. Generate the Sample Report In Data Viewer
   Generate a Sample Report containing the following variables:
   • RECORDING_SESSION_LABEL
     
   • TRIAL_INDEX
     
   • LEFT/RIGHT_FIX_INDEX
     
   • LEFT/RIGHT_GAZE_X
     
   • LEFT/RIGHT_GAZE_Y
     
   • LEFT/RIGHT_VELOCITY_X
     
   • LEFT/RIGHT_VELOCITY_Y
     
   • TARGET_X
     
   • TARGET_Y
     
   • TARGET_VELOCITY_X
     
   • TARGET_VELOCITY_Y
     
   • RESOLUTION_X
     
   • RESOLUTION_Y
     
2. Configure and Run R
   • Set your working directory in R to the folder containing your saved report.
     
   • Edit the script to reference the correct filename for the report.
        
     
   • Run the script.
     

The script automatically detects if the trial contains horizontal or vertical pursuit and runs the appropriate function (PursuitCalcX or PursuitCalcY). For circular or diagonal pursuit, run the X and Y functions separately. The script defaults to analyzing the RIGHT eye. To analyze the LEFT eye, perform a Find & Replace in the script (replace "RIGHT" with "LEFT").

  Pursuit_Script.zip (Size: 1.47 KB / Downloads: 71)

If you have any questions about this script or need assistance adapting it to suit your data, please contact sam@sr-research.com