This manual aims to review some of the technical aspects that GraFIX presents. For more detailed information about this method please read our paper.
GraFIX v. 0.1 System requirements
GraFIX is a multiplatform application developed in C++ and QT frameworks that makes use of Armadillo C++ linear algebra library. The current executable application is deployed for Mac OS X and Windows, even though it can also be deployed for Linux. It requires a minimal screen resolution of 1680x1050 pixels. It works with any binocular or monocular eye tracking system, including SMI, EyeLink or Tobii eye-trackers.
Application overview
The main window consists of a number of boxes where the eye-tracking data and the application’s output is visualized in addition to all the necessary buttons used to manipulate fixations. A brief explanation of these different components is included below.
(1) Menu Bar. The menu bar allows access to different dialogs such as Project configuration, Visualizations or Automatic Detection of Fixations dialogs.
(2) Rough data. The horizontal axis represents time while the vertical axis displays the position of subsequent gaze data-points (Each data-point consists of the x and y coordinates for the right or/and the left eyes.). For binocular systems the right and left eye coordinates are displayed (x-right = Red; x-left = Orange; y-right = Dark blue; y-left = Light blue). In case the system is monocular, the data from the second eye will simply not be displayed.
(3) Filtered data. As for the rough data, the horizontal axis represents time while the vertical axis displays the position of subsequent smoothed gaze data-points. Once the data is filtered the resulting x and y coordinates are displayed.
(4) Pupil dilation. In cases where the eye-tracking system provides pupil dilation data, it is displayed in this box. Further, the average pupil dilation is calculated for each fixation.
(5) Velocity. The horizontal axis represents time while the vertical axis displays the velocity for subsequent gaze data-points.
(6) Missing data from left and right eyes. If there is a data-point missing for either of the eyes it is displayed in this box.
(7) Automatically detected fixations. The orange boxes represent the fixations that are automatically detected by the automatic-detection algorithms.
(8) Flags from the automatic-detection algorithm. During the automatic detection the data is interpolated and the post-hoc validation criteria is applied. The flags indicate which data-points were affected by different algorithms.
(9) The cursor’s current location. A horizontal line is displayed at the cursor’s location facilitating the accurate coding of fixations’ onsets and offsets. Additionally, the From label indicates the line in the rough file where the cursor is located.
(10) Manually coded fixations. The green boxes represent the fixations that can be manipulated manually. Each fixation has a fixation number that matches the numbers from the first column at the fixations list.
(11) Fixations list. This is a list of the fixations that are being manually coded (green boxes). The first column shows the fixation number, the second displays the line in the rough file where the fixation starts, the third displays the line in the rough file where the fixation ends, and finally the fourth column reveals the fixation duration in seconds.
(12) Select the action button. In order to perform an action the corresponding option has to be selected. Once it is selected one will need to click and drag the cursor in order to create, delete or merge fixations. Moreover, it is possible to target smooth-pursuit fixations by selecting this option and dragging the cursor on top of the fixations that need to be coded. In order to add more precision to the task it is possible to enter in the textboxes the start and the end of the fixation that needs to be manipulated, and press Execute. This will execute the action currently selected using the specified start and end points.
(13) Non-active segment. The portion of the screen in grey corresponds to the tasks in the experiment that do not need to be coded.
(14) Active segment. The portion of the screen in white corresponds to the tasks in the experiment that need to be coded.
Input files
Rough data input file
The rough input file is a csv file separated by commas with the following columns:
[(1) Time in microseconds; (2) zeros; (3) relative gaze-point X left eye; (4) relative gaze-point Y left eye; (5) relative gaze-point X right eye; (6) relative gaze-point Y right eye; (7) pupil diameter left eye (optional); and (8) pupil diameter right eye (optional)]
Relative gaze points are values ranging from 0 to 1. Please make sure there are not Inf or -Inf values in your data. When an eye is not detected the value is -1.
If the eye-tracking system is monocular all the columns corresponding to the second eye should be substituted with -1-s.
Segments input file
Sometimes the experimenter will only need to code fixations from certain tasks in the experiment. The segments input file indicates which parts of the experiment need to be coded. If the whole data file is the subject of interest, this file does not need to be included.
The segments input file is a csv file separated by commas with the following columns:
[(1) Segment id, which is an unique number for each row; (2) Row number in the rough file where the segment starts; (3) Row number in the rough file where the segment ends.]
Output files
GraFIX creates a number of csv files that contain the resulting data from the different steps.
File smooth_[subject number].csv This is created after the data is filtered. Each row corresponds to a data point from the rough file, thus both files have the same length. This file is a csv file separated by commas with the following columns:
[(1) Time in microseconds; (2) zeros; (3) smoothed X coordinate; (4) smoothed Y coordinate; (5) velocity; (6) Is saccade flag: 0/1; (7) Is interpolated flag: 0/1; (8) post-hoc merge adjacent fixations flag: 0/1; (9) post-hoc root mean square (RMS) flag: 0/1; (10) post-hoc minimum fixation flag: 0/1]
File fix_auto_[subject number].csv This is created once fixations are automatically estimated. Each row contains the information for one fixation. This file is a csv file separated by commas with the following columns:
[(1) Row from the rough file where the fixation starts; (2) row from the rough file where the fixation ends; (3) duration in seconds; (4) Average X coordinate; (5) Average Y coordinate; (6) RMS; (7) Is smooth pursuit flag: 0/1; (8) Average pupil dilation]
File fix_all_[subject number].csv This file is generated when the first fixation is created and it is updated every time a fixation is manipulated. It is a csv file separated by commas with the following columns:
[(1) Row from the rough file where the fixation starts; (2) row from the rough file where the fixation ends; (3) duration in seconds; (4) Average X coordinate; (5) Average Y coordinate; (6) RMS; (7) Is smooth pursuit flag: 0/1; (8) Average pupil dilation]
Project configuration
To change the project configuration go to Project > Project configuration and the dialog will be displayed. In this dialog we can determine the eye-tracking Hz, the experimental screen resolution (the screen used for testing), and the seconds of eye-tracking data that will be displayed on the screen.
Automatic detection of fixation durations
GraFIX can detect fixations automatically by using adaptive velocity-based algorithms. The present automatic detection algorithms (1) filter the rough data, (2) interpolate missing data points, and (3) apply a number of criteria to evaluate and remove artifactual fixations. The input parameters (e.g. velocity threshold, interpolation latency) can easily be manually adapted to fit the data from different participants that present low or high data quality.
To open the automatic detection of fixation durations dialog go to Operations > Automatic detection of fixations.
It is possible to adapt the parameters by simply changing their values from the sliders. By pressing Estimate fixations GraFIX executes the detection algorithms and displays the results on the orange rectangles. Flags indicating which post-hoc validation criterion was executed are also displayed. This process is relatively fast and thus allows multiple, and easy adjustments of the parameters. When the user acknowledges that the fixations detection is accurate enough, the estimation can be accepted by pressing Accept estimation. This will copy the automatically detected fixations (orange) on the hand-modulated fixations area (green). At this point, the user can review all fixations and manipulate them in order to meet a chosen fixation detection criteria and reduce the noise in the data.
GraFIX is able to run the fixations detection algorithm and visualize the results very quickly. For instance, 30 minutes of data at a sampling frequency of 300 Hz can be parsed in less than a second (obviously, the processing speed depends on the capabilities of the machine where the application is being executed). This permits the user to adjust the input parameters and evaluate their effect on the data in a rapid manner. In fact, it can be immensely helpful (for novice users in particular) to be able to visualize each estimation and see how changing the input values described above will affect the detection of fixations.
Hand-coding fixations
Once the fixations have been automatically calculated, the user can examine and manipulate them in order to fix the algorithms’ outcome. Even the most accurate algorithms may generate a number of artifactual fixations that can corrupt the validity of the experimental results. This is because the data is assumed to have high spatial precision across the whole duration of the experiment, and this is not always the case.
Fixations can be created, deleted or merged by simply clicking and dragging the mouse on the main screen. For instance, in order to create a fixation the user just needs to click the point on the screen where the fixation starts and drag the cursor until the point where the fixation ends. The tag-s From and To located at the upper right of the screen indicate the exact onset and offset of the current fixation (see Figure 2). Once the fixation is created it will appear on the fixations list at the upper left of the screen. If a fixation A starts on the current fragment and ends on the next, we need to (1) create a first fixation whose onset fits with fixation A’s onset and drag the cursor a bit further than the end of the fixations box, (2) create a second fixation on the next fragment whose offset fits with fixation A’s offset, and (3) merge both fixations. Additionally, fixations can be coded as smooth pursuit once they are created.
Evidently the amount of time that the researcher needs to expend coding depends on his/her expertise and on the characteristics of the data (e.g. data quality). Further, accurate detections will require less coding than inaccurate ones, and hence the coding time in these cases will be shorter.
Visualizations
To visualize the eye-tracking data go to Operations > Visualizations. This display allows the visualization of the rough and smoothed eye-tracking data in real-time. Further, it is possible to display the pupil dilations and/or the fixation id-s together with the eye positions. This facilitates the process of coding fixations by replaying those that are not defined clear enough in the main window’s display.
GraFIX includes two different visualization dialogs: Visualize fragment displays the eye-tracking data for the current fragment, while Experimental segments displays the eye-tracking data for all the segments defined at the segments file. Moreover, this dialog allows the inclusion of a background image for each of the segments.
Pupil dilation
If the eye-tracking system includes pupil dilation data, GraFIX is able to deal with it. Once the pupil dilation data is included in the rough input file , it is automatically displayed on the main window. Furthermore, the visualization dialogs include the option to play the eye tracking data together with pupil dilation.
Each fixation that is created or modified by GraFIX includes the pupil dilation means (see 4.8). In case this data was initially not included in the rough file and the fixations have already been coded, it is still possible to include the pupil dilation data in the rough file and recalculate the fixations values. Press Operations > Recalculate current fixation values and the output files will be updated.