INFO: Using the TPLCompleteLabEvents PackageCall [29937]

This article applies to:

E-Prime Extensions for Tobii Pro 3.2

Detail

The PackageCall TPLCompleteLabEvents is an important part to any TobiiProLab-enabled E-Prime experiment. It is a vital routine that sends media and stimulus display information to Tobii Pro Lab for analysis. This article explains the parameters and unique rules for utilizing this PackageCall.

TPLCompleteLabEvents Parameters

The first required parameter is c which is the experiment context that allows users to add variables to the experiment.

The next parameter is vObjectPlaceholderList and it is an optional parameter that identifies objects that have a uniquely named object placeholder image (e.g., Placeholder_Feedback) in the Tobii Pro Lab recording. This parameter accepts a semi-colon delimited list of object names (e.g., "Fixation;Feeback"). This routine only applies to objects that do not have an associated SetDisplayEvent or SendStimulusEvent.

When this parameter is not specified, any visual object without a SetDisplayEvent or SendStimulusEvent is represented in the Tobii Pro Lab recording with a uniquely named placeholder image. Therefore, each visual object is uniquely identified in the Tobii Pro Lab recording by default. When this parameter is specified, only those objects identified in the vObjectPlaceholderList are uniquely represented as placeholders in the Tobii Pro Lab recording. Any visual object that is not listed in vObjectPlaceholderList and is not associated with a SetDisplayEvent or SetStimulusEvent routine is represented in the recording by the current value assigned to the SetPlaceholder call. Any object name specified that has a SetDisplayEvent or is not on the Procedure is ignored. 

The next parameter is vObjectOnsetTimeCustomEventList and it is an optional parameter that identifies objects that have a custom event sent to Tobii Pro Lab. This parameter accepts a semi-colon delimited list of object names (e.g., "Fixation;Feeback"). For any object included in this parameter, the object's onset time and the time in which the object is removed from display are represented in the Tobii Pro Lab recording. Any custom event sent from E-Prime appears as an Imported Event in Tobii Pro Lab.

This parameter is optional and is not specified by default. When not specified, all objects on the Procedure have a custom event sent. When specified, only the object(s) that are listed have a custom event sent. The time in which the object is removed from display is equal to the onset of the next visual object in the Procedure. This is true even if the next visual object is not specified in this parameter.

The next two parameters are both optional. They are vObjectOnsetTimeCustomEventPrefix and vObjectOnsetTimeCustomEventSuffix. vObjectOnsetTimeCustomEventPrefix prepended a prefix value and vObjectOnsetTimeCustomEventSuffix appends a suffix to the custom events sent for onset times. If the parameter is blank, then no prefix or suffix (depending on the parameter) is added to the onset time custom event. Custom names for onset times are in the form (prefix)(objectname_Begin)(suffix).

vStimulusPropertyCustomEventList  is an optional parameter that provides custom event capability for the stimulus object on the procedure for ACC, RESP, and RT values. This parameter accepts a semi-colon delimited list where the first entry is the name of the object to use for the Stimulus object. Subsequent values indicate ACC, RESP, RT values to log as custom events. When not specified, finds the first object on the Procedure that has at least one input mask and a non blank correct response value and sends custom events for that object's ACC, RESP, and RT values. 

The next two parameters are both optional and are the vStimulusPropertyCustomEventPrefix and vStimulusPropertyCustomEventSuffix parameters.

These work identically to the prefix and suffix parameters above. (prefix)(stimulus acc, resp, rt value)(suffix). Custom names for onset times are in the form(prefix)(acc, resp, or rt value)(suffix).

vLastObjectMode is an optional parameter that determines how the last visual object in the Procedure is handled. Accepted values are Linger and Immediate.

When not specified, the last object mode is Linger. When set to linger, no display event is sent to Tobii Pro Lab until the next trial where it can be connected with a future SetDisplayEvent, SendStimulusEvent or part of placeholders in a subsequent call to CompleteLabEvents. When Immediate, a stimulus event is sent to Tobii Pro Lab to complete the object.

vProcessingStartTime is optional and provides the ability for TPLCompleteLabEvents to start processing at a time other than the beginning of the Procedure. When not specified, the entire Procedure is processed. When specified, only objects after the processing start time are considered. This parameter is primarily used when a Procedure has a List object with child procedures that also call TPLCompleteLabEvents.

TPLCompleteLabEvents Guidelines

Because the CompleteLabEvents has a lot of functionality packed into it, there are a couple guidelines that should be followed whenever it is used.

1) Do not place the routine in a Procedure in any location other than the end of the Procedure. For example, if TPLCompleteLabEvents is placed after the Stimulus object but before a Feedback object, then an assertion occurs during runtime. To correct this, the Feedback object must occur before TPLCompleteLabEvents. The exception to this guideline is when a non-visual E-Object (i.e., SoundOut, InLine, etc.) occurs after TPLCompleteLabEvents. Having one of those object after does not throw an assertion.

2) Do not place any visual E-Objects before TPLStartRecording on the procedure where TPLCompleteLabEvents exists. A failure to do so results in a "Stimulus event time interval is out of recording time bounds" error.  This guideline does not apply to non-visual E-Objects (e.g., SoundOut, etc.).

3) 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.

4) Do not include any periods or slashes (forward or back) in the strMediaName parameter of the TPLSetDisplayEvent routine.  A period in the strMediaName parameter causes the same Media File already present in your TPL project to be re-uploaded in each experiment run, or a runtime error. A forward- or backward- slash character in the strMediaName parameter results in a runtime error.

For example, assume that images are located in a local subfolder named Stimuli, the images are defined by an attribute named TargetStim, and that one sample file is named face.bmp. If the strMediaName property were set to "Stimuli/face.bmp" then a runtime error would occur. Instead, do the following:

• assign an attribute to the image filename only with the extension or local path; for example, set an attribute named TargetStim to face
• set the strMediaName property to [TargetStim]
• set the Filename property on the ImageDisplay object or SlideImage sub-object to Stimuli/[TargetStim].bmp

See the TPLFixedPositionAOI sample experiment for an example of how to define and reference media files.