Computational Neuroimaging Laboratory Wiki

The EyeLink eye tracker stores data in the “EyeLink Data Format.” These data files have an .edf file extension and must be converted to ascii before they can be read into matlab. EyeLink provides a utility called 'edf2asc' that will do this conversion. edf2asc is installed in /Applications/EyeLink/EDF_Access_API/Example/edf2asc on the display computer in the psychophysics room (jackson). You can also install it on your own computer by downloading the “EyeLink_Developers_Kit_For_MacOSX” from here:

https://www.sr-support.com/forums/attachment.php?attachmentid=418

Note that you must register with the site before you can download this attachment.

You can find an example stimulus code transientAttn_eyetrack.m as well as the necessary mgl functions on Larmor/CBIV2/Heegerlab/eyetracker_code. Some important segments of the code are explained below:

In the stimulus program (mgl), initialize Eyelink eyetracker, make sure to get gaze data from the Eyelink, open file to record data to, calibrate eye tracker and start recording the eye position:

doEyetracker = 1 
if doEyetracker
  [result dummy] =  EyelinkInit(0);
  if dummy == 1
    disp(sprintf('Eyelink connection running in dummy mode'))
  end
  el=mglEyelinkInitDefaults();
  Eyelink('Command', 'link_sample_data = LEFT,RIGHT,GAZE,AREA');
  edfFile = 'test';
  Eyelink('Openfile', edfFile);
  mglEyelinkDoTrackerSetup(el);
  Eyelink('StartRecording');
end 

In the stimulus program, specify the messages that will be send/recorded. Send a message at the onset of each segment of the trial (for example: trial onset, precue onset, delay onset, stimulus onset etc.). Note that the length of each segment should be a multiple of the monitor refresh rate. According to the Eyelink manual, the messages do not slow down the stimulus program.

Example message at stimulus onset of each trial:

if (task.thistrial.thisseg == 4)
  Eyelink('Message', sprintf('StimulusOnNumber=%i', stimulus.trialnum));
end

In the stimulus program, make sure to stop recording the eye data and end Eyelink:

Eyelink('StopRecording');
Eyelink('CloseFile');
Eyelink('ReceiveFile');
Eyelink('ShutDown');

In the EyeLink manual, it is recommended to calibrate before each run.

Before analyzing the data, you need to change the file format (see above). Convert the .edf file to an ascii file.

You can find an example code on Larmor/CBIV2/Heegerlab/eyetracker_code/parseEyelinkData.m.

parseEyelinkData.m also parses the data using recorded messages sent through the stimulus program (see above) and removes blinks (for example: blinkWin = 100). It saves the data as well as the filtered data (blinks removed) in a .mat file containing the structure eyd. Data and filtData have both 4 columns: time, x position, y position, and pupil size.

Tips and Tricks: After collecting eye data, you can rename each .edf file (e.g. KH_run01.edf). You can edit parseEyelinkData.m easily for each of your subjects by specifying all your .edf files in the variable eyelinkfile. When running parseEyelinkData.m, edf2asc has to be in the same (subject) folder. After running, you can take a look at the ascii file with the TextEditor.

Copy the corresponding stimfiles that contain information about trial type (for statistical comparison) in the same (subject) folder.

Then, run your analysis program.

A bunch of example m-files are posted on Larmor/CBIV2/Heegerlab/eyetracker_code, with eyedata_analysis.m being the main function.

eyedata_analysis.m brings the data in the right format, concatenates x and y positions of each segment and gets rid of the first 2 trials that can be longer than the rest (artifact). It also produces some plots that are useful for an inital check of the data. Here are some example graphs and descriptions:

Plot the actual duration of one segment (here: stimulus on for 30 ms) in samples (here in 0.5 ms, since data was collected with 2000 Hz) for each trial (here: 208). The example graph below shows that the stimulus was displayed between 27 and 30ms.

Mean data across trials (‘time course’): Plot mean x positions (or mean y-positions) vs. time, as well as standard deviations across trials for each time point. X-positions are drift-corrected by the initial fixation period of each trial. The example graph below shows that the mean position is stable during the stimulus period and has a small standard deviation of ~0.5 degrees.

Mean data across time for all trials: Plots mean x positions (or mean y positions) vs. time, as well as standard deviations across time for each trial. Y-positions are drift-corrected by the initial fixation period. The example graph below shows that the mean position is stable across trials and has a small standard deviation of ~1 degree. Note that there are separate plots for x and y positions.

You can sort trials by trial type (for example: cue left, cue right or at fixation).

Plot x vs. y positions for each trial type during stimulus period and add 95% CIs:

Plot mean x vs. mean y positions for each trial type during stimulus period:

2D-position plot for each segment (takes x and y positions at the same time into account):

Also posted on Larmor/CBIV2/Heegerlab/eyetracker_code, you can find plot_saccfrequency.m that gives a first check on saccade frequency. Bar graphs depict frequency of saccades in each segment (here during stimulus and response period). Note that Eyelink option ‘saccade sensitivity’ should be set to ‘high’ before collecting the data.

There are two formats supported by the ASL eye tracker. You want to be using the new format (ver 6000, not ver 5000) that saves more information, including separate traces for the pupil and corneal reflection position. To make sure you are doing that, go to File/File Settings on the Eye tracker control software:

Then you will get a dialog with options for what traces you want to save. The ones that are really important are XDAT (saves digital i/o information including backticks and calibration control bits), pupil_diam, horz_gaze_coord, vert_gaze_coord (normal eye traces) as well as pupil_pos_horz/vert (pupil traces) and cr_pos_horz/vert (corneal reflection traces):

If you are using mgl/task then before each run, you should make sure to run a calibration sequence. You can do this easily by making sure you have the code

myscreen = eyeCalibDisp(myscreen);

in your task, and then hitting space at the beginning of your experiment, when you are prompted:

  -----------------------------
  Hit SPACE to do eye calibration
  ENTER to skip eye calibration
  Esc aborts at any time
  -----------------------------

One thing that is *very important* about eye tracking is to make sure that you calibrate the eye position with the same intensity background as your real task. So if your task has a gray background, do the eye calibration with the identical gray background. Otherwise the reflected luminance off the eye is very different and the eye tracker won't be able to get a good calibration.

Also, for this to work properly, mgl calls a function called:

writeDigPort

which lives in

mgl/utils/readDigPort/writeDigPort.c

Make sure to have the function compiled, by doing:

mex mgl/utils/readDigPort/writeDigPort.c

It is left uncompiled by default so that on computers that don't have the National Instruments board installed it does not choke. If you don't have that function compiled then mgl will not be able to turn on/off the eye tracker automatically and will not be able to send calibration marks. You will know that it is working properly when you run a test of your program and hit space bar for eye calibration. The first time it runs it will take a long time and the cursor will switch to a waiting symbold (several seconds)–this is the program initializing the NI card. After that you can check to see that the eye tracker gets started and stopped appropriately when you start/stop your experiment (you will have to have a file open on the eye tracker control software/have the option set to automatically start and stop and make sure the eye tracker is turned on).

Also, make sure that you have the proper switch set on the backtick control panel to pass the backticks to the eye tracker (I believe it is called external).

You can load the raw eyd files into matlab, by using a function I have in my matlab directory (~justin/proj/mymatlab):

readeyd('xx070601.eyd');

This relies on a mex file so that it can read the file in quickly

readeydseg.c

This will also read 5000 version files although there is not as much information in those files.

If you want to also calibrate the data you can run:

calibeyd('xx070601.eyd')

This function will also allow you to install the calibration into mrLoadRet. Each scan of your experiment will be a “segment” in the file and it will look for calibration marks, when it finds them, it will try to calibrate the data by putting up a figure like:

This is what a good calibration looks like. On occassion the calibrations may not work out quite as well and you have to decide whether to discard them or not. I usually decide based on whether the calibration gives a stable and believable trace for the “Calibrated full timecourse”. If you throw out the calibration, later the program will you ask you which segment to calibrate off of instead. You should pick a segment nearby the segment with the missing calibration.

When you are done, the calibration will be saved to a matlab structure that has a field for horizontal/vertical eye position in degrees of visual angle and also has a field for pupil diameter.

Note that the program is always trying to use the difference between the pupil and corneal reflection as the eye position trace (not the one that the ASL system computes, called horz_gaze_coord since that one sometimes has some weird artifcats in it…) There are times when you may have good pupil information but not a good corneal reflection and may want to do use the pupil only. When you want to do that, you can do:

eyepos = calibeyd('xx070530','hTrace=pupilH','vTrace=pupilV');

or for the corneal reflection trace

eyepos = calibeyd('xx070530','hTrace=cornealReflectionH','vTrace=cornealReflectionV');

Also, the program will put a nan into your trace every time the eye tracker lost the eye position information. It knows this by checking the status field that tells it when the pupil lock or corneal reflection lock was lost and also throws out data when the pupil diameter hits 0. Since usually this means neighboring time points are also bad, it throws out time points on either side of the lost data. Usually it throws out 2 time points, but you can set that with the variable dilationSize. If you want to not throw out any data on either side, do:

calibeyd('xx070530','dilationSize=0');