Tobii Pro Lab and E-Prime
Introduction
E-Prime can be used in combination with Tobii Pro Lab when using the External Presenter project type in Tobii Pro Lab and the E-Prime Extensions for Tobii Pro 3.2. This combination allows the use of E-Prime for stimulus presentation and Tobii Pro Lab for eye tracker data recording and gaze data analysis.
To integrate Tobii eye tracker and Tobii Pro Lab communication into an E-Prime experiment, the E-Prime Extensions for Tobii (EET) software is required. This software includes two E-Prime packages:
- Tobii Pro Lab (TPL) package: described here.
- Tobii Eye Tracker (TET) package: described here (only for the purpose of using in combination with the TPL package) and in E-Prime and Tobii (when using TET solely).
TPL and TET
Below, a description is given on how to use E-Prime as external presenter in Tobii Pro Lab and incorporating a combination of the TPL and TET packages in E-Prime for this purpose. The TET package facilitates eye tracker communication. The TPL package facilitates saving the data in Tobii Pro Lab, thereby making further analysis of the data in Tobii Pro Lab possible. Using the TPL package in combination with TET is recommended when gaze data analysis is required.
When using only the TET package in E-Prime, eye tracker communication is possible, including eye tracker calibration, starting and stopping the eye tracker recording, and saving the raw eye tracking data. When using only the TET package, communication with Tobii Pro Lab is however not possible. Only the raw eye tracking data (gaze/pupil) is saved in a separate txt file. This raw data cannot be further analyzed with Tobii Pro Lab. Using only TET is recommended when the data can be processed without Tobii Pro Lab (e.g. only pupil data in the PhysioData Toolbox). Instructions on using only the TET package in E-Prime can be found in E-Prime and Tobii.
Eye tracker setup
When using a Tobii Pro remote eye tracker (such as the Fusion or X3-120), the eye tracker needs to be configured after connecting it to a computer using the Tobii Pro Eye Tracker Manager. See here for the instructions.
Creating an E-Prime experiment with Tobii Pro Lab integration
For detailed information on how to build Tobii Pro Lab communication in E-Prime, see How to integrate an E-Prime experiment with Tobii Pro Lab and the Tobii Pro Lab User Manual (the desired version can be downloaded from the Tobii website).
In short, the following actions need to be taken:
- Add TobiiEyeTracker and TobiiProLab as Devices to your E-Prime experiment (go to Edit ⇒ Experiment ⇒ Devices ⇒ Add)
- Add the TET and TobiiProLab packages to your E-Prime experiment (go to Edit ⇒ Experiment ⇒ Packages ⇒ Add)
- Add the required package calls of TET and TPL to your E-Prime experiment.
- Create a new project in Tobii Pro Lab and select External Presenter.
- Go to the Record tab in Tobii Pro Lab. It will say the External Presenter is not connected, this is correct. Run the E-Prime task. At the end of the task, return to Tobii Pro Lab to save the recording.
The following information can be sent to Tobii Pro Lab:
- Stimuli onset times.
- Media files. Everything that is displayed to the participant is not automatically sent to Tobii Pro Lab, instead, this has to be specified for each object.
- AOIs and AOI tag information associated with stimuli media. It is also possible to create AOIs and tags afterward in Tobii Pro Lab. An AOI sent from E-Prime to Tobii Pro Lab typically consists of a slide sub-object.
- Response Events. An event can be sent to Tobii Pro Lab when a response is made. This event can convey various response information, such as the accuracy or reaction time of the response.
- Custom Events. A custom event can be sent at any time in the experiment.
Tips & Tricks
Below some important tips, tricks, and considerations when using E-Prime in combination with Tobii Pro Lab are described:
- Set vMode of Movies to “file”. When presenting movies in E-Prime, it is important to set the vMode in the SetDisplayEvent package call to "file" instead of "object" (default) or "fullscreen". When “object” or “fullscreen” vMode is used, only a still of the movie is sent to Tobii Pro Lab, instead of the whole movie.
- Define the Tobii Pro Lab project name in TPLOpen. In E-Prime, define the name of the project in the TPLOpen package call. When doing so, E-Prime will check whether the right Tobii Pro Lab project is open during runtime. When the specified project is not open, E-Prime will throw a warning message.
- Sending data to Tobii Pro Lab takes time. In Tobii Pro Lab, the duration of the object that is located just before the TPLCompleteLabEvents package call, is longer than is set in E-Prime. This delay is dependent on the amount of data that needs to be sent to Tobii Pro Lab (see also point below: Pilot the study to pre-load media files).
- Pilot the study to pre-load media files. Pilot the final study at least once before starting with the experimental sessions so that the media files are already uploaded to the Tobii Pro Lab project. This will prevent unwanted delays during the first actual run. Subsequent experimental sessions will not repeat this upload (see for more information: EET: Sending media files to Tobii Pro Lab prior to data collection [30416]). Important considerations when doing the pilot:
- Use the SetAOIAddMode and set it to “Always” during the pilot and “Never” during the experimental sessions. The SetAOIAddMode determines whether AOI calls and Tag creation calls execute. This will significantly reduce the delay of the object located just before the TPLCompleteLabEvents package call (e.g. using E-Prime’s TPLFixedPositionAOI experiment which includes only simple picture stimuli, the delay was reduced from about 500 ms to 100-200 ms).
- Check in your Tobii Pro Lab experiment whether the right and all media files are present after the pilot.
- Check for UploadMedia warning messages in the E-Studio Output window after running the pilot. This message is generated when media is uploaded to Tobii Pro Lab and should therefore not occur during the experimental sessions.
- The pilot and experimental sessions must write to the same Tobii Pro Lab project. Make sure that the Tobii Pro Lab project name is specified in the TPLOpen package call.
- The calibration results of the calibration performed by E-Prime are not saved in Tobii Pro Lab. The calibration results can thus not be viewed or exported after data collection. The calibration in E-Prime does not provide precision and accuracy metrics like Tobii Pro Lab does, but only provides a graphical representation of the offset. The calibration results can be saved by E-Prime, below is an example on how to save the results in a separate text file, which is highly recommended.
- Port 8080 in use. Tobii Pro Lab’s External Presenter API uses port 8080 (this is also set as default in the TobiiProLab device in Devices in E-Studio). It is however possible that another application is already using port 8080. In this case, E-Prime throws the following error during runtime: “localhost could not be reached on port 8080”. The application that is using port 8080 can be found and closed, or an alternative port can be set for Tobii Pro Lab (see ERROR: TPLOpen fails to connect when port 8080 is not available or localhost does not resolve to 127.0.0.1). Both methods require Admin rights.
- strMediaName in TPLSetDisplayEvent should not include a period (and thus not the file extension). When using a period in the strMediaName, the media will be uploaded to Tobii Pro Lab each time the task is run, instead of only once the first time the task is run. Make sure to not include the file extension (e.g. .mp4) in the strMediaName. Also when referencing an attribute, make sure the attribute does not include the extension. When referencing the same attribute as the media object's filename property does, the extension can be added in the media object's filename property (e.g. [movieFile].mp4).
- Do not use Label objects and GoTo statements to jump over visual display E-Objects. This causes a runtime error to occur because TPLCompleteLabEvents cannot process all of the E-Objects because one or more of them was skipped.
- Other TPLCompleteLabEvents important guidelines can be found here: INFO: Using the TPLCompleteLabEvents PackageCall [29937]
- Use Windows 10. The TPL package should be used in Windows 10. In Windows 7, Tobii Pro Lab does not show the media sent from E-Prime correctly (see also: BUG: Tobii Pro Lab media is not shown correctly when running on Windows 7 [30978]).
Saving the calibration results
Because the calibration results are not saved in Tobii Pro Lab, it is highly advised to separately save them. Note that these calibration results are not as informative as the calibration results provided by Tobii Pro Lab. That is, precision and accuracy metrics are not provided, only the position of each calibration point and associated position of the mapped point in percentages of the screen are provided.
Saving the calibration results in E-Prime is done by adding an Inline after the Calibration object in your task...
...and adding the following information to this inline (some documentation from E-Prime is provided at the top):
'This function gets information about a calibration for a quality inspection.
'The inspection is easiest implemented as viewing the data to manually approve
'it or take necessary action to improve it. Provided are target points, the
'resulting mapped points, and an indication whether or not the point was
'discarded, by the eye tracker. The result is from the current calibration
'in use. Returns calibration information as a TobiiCalibAnalyzeDataCollection
' Object.
'
'A TobiiCalibAnalyzeDataCollection Object is a collection of TobiiCalibAnalyzeData type.
'The TobiiCalibAnalyzeData type consists of these values:
'- TruePointX (Double): Horizontal position of the gaze point target where it was displayed to the subject.
'- TruePointY (Double): Vertical position of the gaze point target where it was displayed to the subject.
'- LeftMapX (Double): Horizontal position of the mapped point for the left eye.
'- LeftMapY (Double): Vertical position of the mapped point for the left eye.
'- LeftValidity (Long): Left eye, (-1) - was not found, (0) - found but not used, (1) - used.
'- RightMapX (Double): Horizontal position of the mapped point for the right eye.
'- RightMapY (Double): Vertical position of the mapped point for the right eye.
'- RightValidity (Long): Right eye, (-1) - was not found, (0) - found but not used, (1) - used.
'The purpose of CalibGetResult() is to inspect the data to see how good the samples were in order to
'approve the calibration to improve it or to redo it.
'The data consists of the true point (where the participant gazed at) and where the sample was
'mapped to, using the calibration that was partly based on the sample itself.
'Note that some points are not part of the calibration. It is those for which the eye was found by the
'eye tracker or those for which the eye tracker found them but discarded them for other reasons.
'The LeftValidity and RightValidity values indicate whether it was used or not.
'Following sample code saves the calibration results in a text file:
Dim tc As TobiiCalibAnalyzeDataCollection
Set tc = TobiiEyeTracker.CalibGetResult()
Dim calibCounter As Integer
If tc Is Nothing Then
Err.Raise TET_ERR_CORE_DEVICE_CANT_OPEN, , _
"Unable to gather any calibration results. Please consider restarting this experiment."
Else
For calibCounter = 1 To tc.Count
Dim tdat As TobiiCalibAnalyzeData
Set tdat = tc(calibCounter)
Open C.GetAttrib("Experiment") & "-" & C.GetAttrib("Subject") _
& "-" & C.GetAttrib("Session") & "-Calibration.txt" For Append As #5
Print #5, "Sample: " & CStr(calibCounter)
Print #5, "TruePointX: " & CStr(tdat.TruePointX)
Print #5, "TruePointY: " & CStr(tdat.TruePointY)
Print #5, "LeftMapX: " & CStr(tdat.LeftMapX)
Print #5, "LeftMapY: " & CStr(tdat.LeftMapY)
Print #5, "LeftValidity: " & CStr(tdat.LeftValidity)
Print #5, "RightMapX: " & CStr(tdat.RightMapX)
Print #5, "RightMapY: " & CStr(tdat.RightMapY)
Print #5, "RightValidity:" & CStr(tdat.RightValidity)
Print #5, ""
Close #5
Next calibCounter
End If