EET: Sending media files to Tobii Pro Lab prior to data collection [30416]

This article applies to:
E-Prime Extensions for Tobii Pro 3.2

 
Detail
E-Prime users are strongly urged to pilot their experiments prior to beginning data collection. Piloting includes not only testing the details of the experiment execution but also confirming that data is logged properly and that the planned data analysis can be performed. See GETTING STARTED: Considerations in Computerized Research [22680] for general recommendations for running pilot studies. The advantages to running pilot studies increases with more complex experiments. This is particularly true for experiments that incorporate E-Prime Extensions and/or interface with other hardware and software components, including any TobiiProLab-enabled experiment. Tobii Pro also recommends running pilot studies; see Tip #2 in the "Experiment eye tracking tips" blog article.
 
E-Prime Extensions for Tobii Pro 3.2 users can take advantage of an additional benefit of piloting their study: pre-loading media files along with any associated AOIs and tags to the Tobii Pro Lab project. Doing so can reduce potentially long and distracting Inter-Trial Intervals (ITIs) from occurring during data collection. The time that is required to send media files and their associated AOIs and tags is dependent upon their size and quantity. Most TobiiProLab-enabled experiments include one or more calls to the SetDisplayEvent routine. SetDisplayEvent identifies a visual display to be represented in Tobii Pro Lab. Additionally, one or more calls to SetAOI and SetTag may occur. These calls identify the AOIs and Tags are created on their corresponding display representations. The CompleteLabEvents routine ensures that these visual display elements are transmistted to Tobii Pro Lab by calling UploadMedia (see below). Experiments with particularly large media files and/or large numbers of AOIs and tags per media file may exhibit noticeable delays at the end of a procedure when the CompleteLabEvents routine is called. Running pilot sessions of the experiment is often the simplest way to upload experiment elements and avoid delays during data collection sessions, because E-Prime only uploads a single copy of each uniquely named media file. If a media file already exists in Tobii Pro Lab, then the CompleteLabEvents routine will not attempt to upload a second copy. Therefore, pilot sessions can be used for the potentially time-consuming process of uploading. Subsequent experiment sessions will not repeat the upload and therefore will not exhibit delays.
 
An alternative method to running a pilot is to call the DefineMedia (or UploadMedia, for movies) PackageCall routines. This method is better suited to experiments with only a few media files that are particularly large (although piloting remains a recommended Best Practice, for other reasons). Both methods are described below.
 
Pilot the experiment
There are numerous ways to setup the pilot. The pilot session can be run from the main experiment specification (.es3) file. The pilot sessions could also be run from a different specification file, as long as media names between the pilot and experimental specifications are the same. The complexity of the between-subject manipulations may dictate how many pilot sessions need to be run. For example, if lists of stimuli are counterbalanced across subjects based on subject number, then you would need to run one subject number for each counterbalance condition in order to present all of the stimuli. However, the key elements of the pilot study are as follows:
 
* The pilot and experimental sessions must write to the same Tobii Pro Lab project:
An E-Prime experiment communicates with the current Tobii Pro Lab project. The Tobii Pro Lab software must be opened to the Record tab of an External Presenter project prior to launching the E-Prime experiment. (See Tutorial 5, Task 14 in the E-Prime Extensions for Tobii 3.2 User Manual for details.) A specific Tobii Pro Lab project cannot be opened from E-Prime. Therefore, Tobii Pro Lab must be opened to the same project prior to running the pilot that is opened prior to running the experiment session. In general, PST recommends using the optional parameter on the TobiiProLab_Open routine to specify the expected project name. This helps to ensure that both the pilot and experimental sessions are writing to the expected project.
 
* The pilot session must set the SetAOIAddMode to "Always" while the experimental sessions must set the SetAOIAddMode to "Never":
The SetAOIAddMode routine determines if the AOI calls (SetAOI, SetAOIR, SetAOIP, SetAOIKeyframes) and any associated Tag creation calls (SetTag) execute. These calls should all execute in the pilot sessions but not in the experimental sessions. Once the desired AOIs and Tags are sent to Tobii Pro Lab, the SetAOIAddMode can be set to "Never" to no longer upload AOIs and Tags. Additionally, "Always" can be specified after collecting participant data in order to add additional AOIs and Tags.
 
* Consider using the AutoResponse feature while piloting:
The AutoResponse feature can enable pilot sessions to be run more quickly and with less experimenter attention and input. See article E-STUDIO: Auto Response [22738] for details.
 
* Confirm that no "upload media" warning messages appear in the E-Studio Output window after running all pilot conditions:
E-Prime includes a warning about calls to the UploadMedia routine in the Output Window (see E-STUDIO: Output Window [22696]). Each time the UploadMedia routine executes while the experiment is running, a warning is generated. However, if all of the display objects that are processed with the CompleteLabEvents PackageCall routine have already been created as media files in Tobii Pro Lab, then the UploadMedia PackageCall routine does not execute and therefore no UploadMedia warning appears. Therefore, if the pilot session(s) has (have) resulted in all media files being sent to Tobii Pro Lab, then no experimental session will include any warnings related to the UploadMedia routine. The image below shows the Output tab after running an experiment that calls UploadMedia. No such warnings should appear in the Output tab when running experimental subjects if the previously run pilot sessions uploaded all referenced stimulus displays.

 
Use DefineMedia/UploadMedia routines
An alternative to the pilot study approach is to manually call the Tobii Pro Lab PackageCall routines that create and send the media files of interest to the Tobii Pro Lab project.
 
* DefineMedia:
DefineMedia is responsible for creating a representation of an E-Prime display and sending that representation to Tobii Pro Lab. Most users will not need to call DefineMedia; it is called automatically by other routines, primarily SetDisplayEvent and SetPlaceholder that are used to define critical stimulus events. DefineMedia has 3 parameters. The first parameter is c (the experiment context) and is specified as the first parameter for the majority of PackageCall routines. The second parameter, strMediaName, identifies the name of the media file to be created in Tobii Pro Lab. The final parameter, strObjectName, is the name of the object whose display characteristics are to be represented in the media file.
 
The DefineMedia routine needs to be called on the same procedure as the strObjectName. For example, if the object of interest is presented on a procedure named TrialProc, then the DefineMedia routine must also be called on the TrialProc. Further, the DefineMedia routine should be called after the strObject is called to ensure that any attribute references have been resolved prior to generating a likeness of the stimulus display.
 
The DefineMedia routine is responsible for capturing a representation of a static image display.  It calls UploadMedia internally, which is the routine responsible for transmitting the corresponding media file in Tobii Pro Lab. Since DefineMedia can only generate static displays, it cannot be used to create media files for movies.
 
* UploadMedia:
UploadMedia sends a representation of an E-Prime display to the Tobii Pro Lab interface; these representations are shown both during the playback of the recording and in the thumbnail timeline. UploadMedia has 2 required parameters, strPath and strMediaName. strPath is a string value of the name of the file to be uploaded to Tobii Pro Lab. It must include path information if the file is not in the same folder as the experiment. To create a Tobii Pro Lab media file from a movie, specify the movie file as the strPath parameter. Set strMediaName to the name of the media file in Tobii Pro Lab. 
 
The attached experiment illustrates how to call DefineMedia and UploadMedia. Note that the experiment also requires the 2 attached .png files and the movie file to be placed in the same folder as the .es3 file.