Introduction

To integrate Tobii eye tracker communication into an E-Prime experiment, the E-Prime Extensions for Tobii (EET) software is required. This software includes two E-Prime packages:

• Tobii Eye Tracker (TET) package
• Tobii Pro Lab (TPL) package

Below, a description is given of how to use TET in E-Prime 3 and E-Prime 2. In general, this package facilitates eye tracker calibration, starting and stopping the eye tracker recording, and saving the raw eye tracker data in E-Prime. 

For more information on the TPL package and how to incorporate E-Prime as external presenter in Tobii Pro Lab, see Tobii Pro Lab and E-Prime.

Availability, support and advice

EET 3.2 and EET 2 are available for researchers of FSW Leiden and are preinstalled on all lab computers. EET 3.2 can be installed on work computers through the Software Center.

SOLO provides full support on EET. The TET package is recommended when only pupil size needs to be obtained, or when the gaze data can be analyzed independently of a GUI. A combination of the TET and TPL package is recommended when the gaze data needs to be analyzed with Tobii Pro Lab (see Tobii Pro Lab and E-Prime). See here for a full software guide for Tobii eye trackers.

E-Prime 3 and EET 3.2

When building an E-Prime experiment with Tobii eye tracking, using E-Prime 3.0.3.80 with E-Prime Extensions for Tobii 3.2.1.105 (henceforth referred to as EET 3.2) is recommended over using E-Prime 2 with EET 2. This is because the EET version is improved, the gazedata is saved faster, and building eye tracking in your task is much more user friendly. Note that compared to EET 2, some significant changes were implemented in EET 3.2 (see EET 3.2 changes and bugs).

Documentation and Getting Help

• SOLO sample task (download starts immediately)
  The sample task located in EET 3.2 includes the ObjectOnScreen workaround as described below.
• PST official sample tasks
  When the EET package is installed on your computer, you can also obtain the EET sample tasks by opening E-Studio, going to Tools ⇒ Options, and then click Copy Samples and Tutorials to My Experiments Folder. Samples are now located on your computer in C:\Users\<username>\Documents\My Experiments\3.0\Tobii Pro\Samples\TET. The TETPictureRT is a very basic experiment, which could be a good start for your eye tracking experiment. Note that the TETWaitForFixation object and TETGazeReplay objects are usually not necessary.
• User Manual
  Another helpful tool is the User Manual. This manual also includes tutorials. When the EET package is installed, you should be able to find the User Manual on your computer when you go to Start ⇒ E-Prime Extensions for Tobii Pro. The latest version of the User Manual can also be downloaded here.

Short manual

The steps of how to add basic eye-tracking functionality to an E-Prime 3 experiment are described below:

• Add the EET package to your experiment by going to: Edit ⇒ Experiment ⇒ Packages ⇒ Add ⇒ select TET and click OK. When the TET package is not available, EET is probably not (properly) installed.
• Add the TobiiEyeTracker device by going to: Edit ⇒ Experiment ⇒ Devices ⇒ Add ⇒ select TobiiEyeTracker and click OK. When the TobiiEyeTracker device is not available, EET is probably not (properly) installed or the EET package path is not added to E-prime.
  To add the package path to E-prime goto Tools ⇒ Options and open the package tab.
  Click on the square to add a path and browse to C:\Program Files (x86)\PST\E-Prime Extensions for Tobii Pro 3.2\Packages\TET and press apply. Restart E-prime and the EET package should be available now in the experiment properties.
• Double click on the TobiiEyeTracker device. Select your eye tracker (when the eye tracker is connected to the computer) under Eye Tracker. Also, select the right sampling frequency of the eye tracker under Frequency. The Max Count is the maximum number of samples that can be collected during a trial. This should be at least the complete trial duration (including response time) in seconds multiplied by the sampling frequency of the eye tracker. For example, when a trial lasts for 10 seconds, and the eye tracker measures with a sampling frequency of 120 Hz, the Max Count should be set to at least: 10 x 120 = 1200. When multiple displays are used, select the right display under Display.
• At the start of the task, add a TETOpen, TETCalibRegular, and TETGazeDataOpen package call (see sample task and User Manual).
  • TETOpen: The TETOpen package call opens TET communication. The default parameters are usually sufficient.
  • TETCalibRegular: Performs a typical calibration. In the parameters you can set the number of calibration points. The default is 5. Note that the calibration results are not saved, follow the instructions on the Tobii Pro Lab and E-Prime page to save the calibration results in a separate text file.
  • TETGazeDataOpen: Opens the gazedata file. In the parameters you can set the user defined columns in the gazedata file. These are extra columns that are added to the gazedata file, next to the columns that are saved by default. Here you can for example specify the trial type or other trial information. For an example, see the sample tasks. It is very important to think carefully about what information to save as it can be very useful to add metadata columns. In the parameters, add columns within quotation marks, separated by a semicolon (e.g. “Prime;AOI1;AOI2”).
• At the end of the task, add a TETGazeDataClose and TETClose package call.
  • TETGazeDataClose: Closes the gazedata file. No parameters to be set.
  • TETClose: Closes TET communications. The default parameters are usually sufficient.
• At the start of the trial procedure, add a TETGazeDataSetProperty and TETStartTracking package call.
  • TETGazeDataSetProperty: Writes values to the user specified columns when the gazedata is saved. Each column defined in TETGazeDataOpen can here be filled with a value. In the parameters of this package call, the column name is first written in quotation marks, followed by the value that needs to be written to the corresponding column. When referring to an attribute, the attribute should be written in square brackets. Then, the next column and value is specified. For example: “Prime”, [Prime], “AOI1”, [LeftImage], “AOI2”, [RightImage]. Note that the TETGazeDataSetProperty object can also be placed at a later point in the trial procedure. This could be relevant when the values of the attributes are not known yet at the start of the procedure (see also the FAQ).
  • TETStartTracking: Start the Tobii eye tracker recording. The default parameters are usually sufficient.
• At the end of the trial procedure, add a TETStopTracking and TETGazeDataSave package call.
  • TETStopTracking: Stops the Tobii eye tracker recording. The default parameters are usually sufficient.
  • TETGazeDataSave: Saves the gazedata from the Tobii eye tracker’s history to the gazedata text file. Here, an optional parameter can be specified to log the dependent measures of an object (e.g. “Stimulus”). That is, the ACC, CRESP, RESP, and RT are logged in the gazedata file of the object specified in this package call.

Next to these basic package calls, there are other package calls available. See the sample tasks and User Manual for more information.

Calibration

It should be noted that the calibration data is not saved anywhere. Follow the instructions on the Tobii Pro Lab and E-Prime page to save the calibration results in a separate text file. Note that this has already been implemented in the sample task that can be downloaded from Github (download starts immediately).

Saving Event data in the gazedata file

It is possible to save a variable that has event like properties in the gazedata file. That is, a column can be added to the gazedata file in which for each data row (sample) the name of the Object is stored that was presented on screen at that current time. When further processing the data with the PhysioData Toolbox, this variable can be converted to labels, which can be used for segmenting the data.

Automatically, EET 3.2 saves a variable called CurrentObject. This variable holds the name of the object that was running, however, this variable is only stored when the participant was looking at the screen. More specifically, only rows with valid data show a CurrentObject. It is thus possible that the start or end of a certain object is not stored in the gazedata file when the participant was looking away from the screen or blinking at the start or end of the object. Note that after the eye is lost, the CurrentObject variable is by default still stored for 300 ms. This is meant as blink compensation period and the default of 300 ms can be overridden through the use of a TobiiEyeTrackerDevice.GazeData.BlinkCompensationDuration start-up parameter specified in milliseconds.

Following the above, it is highly advised to save another variable in the gazedata file, called ObjectOnScreen, which saves the object presented on screen, regardless of whether the participant was looking at the screen or not. Note that only objects that have a display component are saved in the ObjectOnScreen variable. Objects that do not have a display component, such as Wait or SoundOut objects are not logged. To add this variable to the gazedata file, follow the following steps. Note that this has already been implemented in the sample task that can be downloaded from Github (download starts immediately).

• Create a TETGazeDataDefineProperty object and place it right after the TETGazeDataOpen object. Open the TETGazeDataDefineProperty and define the following parameters: c, “ObjectOnScreen”
• Create an InLine object and place it right before the TETGazeDataSave object.
• Place the following code in this InLine:

Data

The eye tracker data is saved in a text file. This file is saved in the same folder as where the E-Prime task is located. The file holds the data per sample (for example, with a sampling rate of 120 Hz there will be 120 samples (rows) per second). The CursorX and CursorY variables hold the gaze position in pixels on the screen. Another useful variable is ComponentName, which is the name of the component in the experiment that is being looked at by the participant (see the user guide for more information on the variables that are saved). Only raw gaze data is saved, the gaze data is thus not categorized in fixations or saccades.

The PhysioData Toolbox can be used to analyze the data. The PhysioData Toolbox allows segmenting the data into epochs and can output pupil and area of interest hit metrics per epoch. See the PhysioData Toolbox website for more information. There are no ready-made tools for extensive gaze analysis of the gazedata files available. Custom made solutions that require advanced programming skills are therefore required, or the combination of E-Prime and Tobii Pro Lab should be used. 

E-Prime 2 and EET 2

Documentation and Getting Help

• Sample tasks.
  Adding eye tracking to an E-Prime 2 experiment can be quite tricky. Sample tasks are indispensable when creating an eye tracking task in E-Prime 2. When the EET package is installed on your computer, you can also obtain the EET sample tasks by opening E-Studio, going to Tools ⇒ Options, and then click Copy Samples and Tutorials to My Experiments Folder. Samples are now located on your computer in C:\Users\<username>\Documents\My Experiments\Tobii\Samples\TET. The TETPictureRT is a very basic experiment, which could be a good start for your eye-tracking experiment. Note that the TETWaitForFixation and TETGazeReplay objects are usually not necessary.
• User Manual.
  Another helpful tool is the User Manual. This manual also includes tutorials. When the EET package is installed, you should also be able to find the User Manual on your computer when you go to Start ⇒ E-Prime Extensions for Tobii.
• Youtube.
  For more information about how to add Tobii package calls to your experiment see: E-Prime 2.0: Adding EET Package Calls. For more information about setting up the whole task with eye-tracking, including information about the User Script and SaveGazeData InLine, see: E-Prime 3 Live Stream: E-Prime Extensions for Tobii. Although E-Prime 3 is used in this last video, it is used in combination with EET 3.1, which is functionally identical to EET 2 an thus the steps taken are exactly the same as in E-Prime 2 and EET 2.

Short Manual

Note that for E-Prime 2 with EET2 a task that includes EET package calls and the TobiiEyeTracker device can only be opened when the EET package is installed. Make sure you have the EET package installed on your computer. Sometimes, the task will not open unless an eye tracker is connected to the computer.

• Add the package to your experiment by going to: Edit ⇒ Experiment ⇒ Packages ⇒ Add ⇒ select TET and click OK. When the TET package is not available, EET is probably not (properly) installed.
• Add the TobiiEyeTracker device by going to: Edit ⇒ Experiment ⇒ Devices ⇒ Add ⇒ select TobiiEyeTracker and click OK. When the TobiiEyeTracker device is not available, EET is probably not (properly) installed.
• Double click on the TobiiEyeTracker device. Here, the eye tracker address should be entered in IP Address/Name. You can find the eye tracker address in the program Eyetracker Browser. Go to Start ⇒ Tobii ⇒ Eyetracker Browser. Press copy to copy the address, then paste it in E-Prime in the IP Address/Name field in the TobiiEyeTracker device.
• At the start of the task, add a TETOpen, TETOpenGazeDataFile, and TETCalib package call.
• At the end of the task, add a TETCloseGazeDataFile and TETClose package call.
• At the start of the trial procedure, add a TETStartTracking package call.
• At the end of the trial procedure, add a TETStopTracking package call.
• After the TETStopTracking package call, add an InLine and name in SaveGazeData.
• From the sample task, copy the User Script to the User Script of your experiment.
• From the sample task, copy the content of the SaveGazeData InLine to the SaveGazeData InLine of you experiment.
• In the User Script, the variables that are saved in the gazedata file are defined. This needs to be adjusted to your experiment, by removing or adding variables.
• In the SaveGazeData InLine, the variables are written to the gazedata file. The contents of this InLine need to be adjusted to your experiment.
• See E-Prime 3 Live Stream: E-Prime Extensions for Tobii for more information about the User Script and SaveGazeData InLine.

Saving event data in the gazedata file

When following the steps described above and when adjusting the SaveGazeData InLine for your experiment design, a variable called CurrentObject is saved to the gazedata file. Using EET 2, this variable holds the object that was presented on the screen, regardless of whether the participant was looking at the screen or not. When the data is further processed with the PhysioData Toolbox, this variable can be converted to events and used for segmenting the data.

Data

The eyetracking data is saved in a .gazedata file. This file is saved in the same folder as where the E-Prime task is located. The gazedata file can be opened in Excel. The file holds the data per sample (for example, with a sampling rate of 120 Hz there will be 120 samples (rows) per second). The CursorX and CursorY variables hold the gaze position in pixels on the screen. Only raw gaze data is saved, the gaze data is thus not categorized in fixations or saccades.

The PhysioData Toolbox can be used to analyze the data. The PhysioData Toolbox allows segmenting the data into epochs and can output pupil and area of interest hit metrics per epoch. See the PhysioData Toolbox website for more information. There are no ready-made tools for extensive gaze analysis of the gazedata files available. Custom made solutions that require advanced programming skills are therefore required.

Important note!

When measuring pupil size, E-Prime 2 and EET2 cannot be used in combination with the X3-120 eye tracker. This is because of the following:

The Tobii X3-120 eye tracker uses two modes of tracking the eye: bright mode and dark mode. The order that the eye tracker uses these modes in is: 1 bright – 2 dark. Pupil size should only be reported during bright mode (this thus results in a sampling rate of pupil size of 40 Hz). However, in combination with E-Prime 2, pupil size is reported in both bright and dark mode. It is unfortunately impossible to know which mode has been used for which sample. The interchangeable use of the two modes causes a lot of noise in the pupil data. Thus, we strongly advise against using the X3-120 eye tracker in combination with E-Prime 2. In E-Prime 3 the issue is solved and pupil size is only reported during bright mode. The Tobii X2-60 eye tracker also uses both bright and dark mode. However, during the recording only one of the two modes is used. The best tracking mode is established during calibration. Only when tracking is completely lost, (not during blinks, but when the participant looks away for a longer period of time), the tracking mode is reevaluated. Thus, all pupil size samples can be used when using a X2-60 eye tracker. Note: Bright mode means that the pupil lights up. This is because the infrared light directly hits the pupil. In dark mode, the pupil is darker than its surroundings. This is because the infrared light hits the pupil under a certain angle.

See also: Dark and bright pupil tracking.

 FAQ