MATLAB code for identifying fixations via POR data

Instructions (some of this stuff will be simplified later)

1. Download all the MATLAB files listed on this page into the same folder (remember where this folder is!). Run subject, calibrate, save eye tracker data (into text file or .tda).
2. Open data file that contains POR data. For ISCAN data, this would be the file with extension .tda, for Yarbus this would be a .txt file.
   • Make sure that you are in the directory that contains open_eyetracker_data.m. You can type 'ls' in the command line to see the contents of the active directory. If you are not in the right directory, select the button with the three dots next to the drop down field where the current directory appears and browse the the director. Now, in the command line, type:
     • open_eyetracker_data('ISCAN') % to open an ISCAN data file.
     • open_eyetracker_data('Yarbus') % to open a Yarbus data file.
       • there may be bugs here, only tested it with one data file!
       • NOTE: Yarbus data file uses "calX" and "calY" for what I (and ISCAN) refer to as horizontal and vertical POR (respectively).
   • For any other data file, type open_eyetracker_data('other'). A GUI will pop up that will ask you to enter in the number of header lines (this is the number of lines before the first data values appear. For example, if there are a bunch of lines before the data columns that contain stats on the data and then the headings of the columns start on line 9 and the values start on line 10, the number of header lines would be 9. Then you will enter the total number of columns (of data) and the column number that each data is in.
3. The open_eyetracker_data function will save a file named eyedata.mat. RESAVE this file with a specific name (e.g., ChangeBlindness_Subject1_June10_2008_eyedata.mat):
   • In command line type> load eyedata.mat
   • Then type> save new_filename.mat (e.g., save ChangeBlindness_Subject1_June10_2008_eyedata.mat). This will be the file that you load any time you want to access this data. You can check that things look right by typing plot( POR_H, POR_V, 'x') to plot vertical POR versus horizontal POR data points denoted with x's. If there's a ton of data or lots of track losses, this plot may just look like a mess. Alternatively, you can type plot(Pupil_H) to plot the horizontal pupil data (versus sample number) which might look better.
4. Set up desired parameters for fixation-identification. This will be made nicer later but for now open up identify_fixations.m and alter the desired parameters (if you screw up something, you can redownload the m-file here!):
   • minfixlength = this is the minimum number of consecutive FRAMES (not seconds, not data samples) that the PORs must "match" in in order to be considered part of a fixation. Default is 6 (200 ms) but change it to whatever you want if you don't like that!
   • maxfixlength = if the fixation duration exceeds this number of consecutive FRAMES, it will be ended and a new fixation started (if the correct number of PORs match later). Default is infinity (no max) and probably should be left that way (cause just ending the fixation at this number is not a very sophisticated way to deal with fixations that are too long...
   • imsize = this helps us determine if the POR is a track loss (out of image bounds). Default is set to 480x720 (HEIGHT by WIDTH - thats the way MATLAB likes it!) which is standard and works with the portable tracker and any video collected by a standard video camera (i.e., for the HD camera this would need to be changed to [1080 1920]).
   • startat = sample number to start processing at. Default = 1;
   • endat = sample number to end processing at. Default is the total number of samples in the loaded eye data (if you want to change this, you should probably just comment at the rest of the line so you can go back to it when you want to).
   • dmax = Maximum allowable distance between two consecutive PORs that can be considered to be part of the same fixation. I suggest using 10 for stationary subjects (not like bolted in a chin rest or anything, but subjects that aren't moving the head around much or doing to much physical activity during the task) and 25 for subjects walking around and wearing the portable eye tracker (this way VOR movements which may make the POR move quickly through the image can still be grouped into fixations on a single target).
5. Run fixation-identification routine. Eye data should be loaded, if not type load eyedata.mat or load your_filename.mat at the command line. Then to start fixation-identification routine type: identify_fixations once again, make sure you are in the appropriate directory (see Step 1).
6. Save results with new filename (e.g., save ChangeBlindness_Subject1_June10_2008_fixationdata.mat).

Analysing the results

• I'll update this another time (I'm tired!)

References

• Munn_Stefano_Pelz_APGV08_Version2BPublished.pdf: APGV paper on comparing this fixation-identification routine to manual coders (final version submitted for publication with color plate).
• Identifying_fixations_and_saccades_in_eye_tracking_protocols_ETRA00.pdf: Taxonomy of various fixation-identification routines.

MATLAB m-files

• Current versions are working but not beautifully commented! That will come later!
• identify_fixations.m: main MATLAB script for identifying fixations from POR data
• Supplementary files required to run identify_fixations:
  • matchPORs_distance.m
  • check4trackloss.m
• open_eyetracker_data.m: MATLAB file for opening eye tracking data (ISCAN or Yarbus)

Examples

• I'll update this another time (I'm tired!)

Privileges

• Set ALLOWTOPICCHANGE = VplGroup

-- SueKola - 24 Jun 2008