E-STUDIO: Using Task Events [22862]

The Task Events feature in E-Prime expands E-Prime's synchronization capabilities by offering a wide variety of options to take action when specific time critical events occur during an experiment.  Task Events can be thought of in terms of “cause and effect,” where the cause is the Event (e.g., incorrect response, click of a button, onset time of an object, etc.) that triggers the effect, or the Task (e.g., run a series of script commands, send a signal to the serial port, etc.).  For example, your experiment may require that a signal be sent to a port to indicate the time when the stimulus is displayed. In this example, the display of the stimulus is the Event/cause that triggers the signal to be sent (i.e., Task/effect).
 
Task Events are configured on the object to which they are related, which is determined by the needs of the experiment. For example, if the user would like to send a signal from E-Prime to an external device at the time the stimulus is displayed, the Task Event should be configured on the object presenting the stimulus. If the desired Event is related to the participant's response, the Task Event should be configured on the object that enables the Input Mask (i.e., collects the input).  
 
NOTE: If PreRelease is in use, it may be necessary to specify the Task Event on the next occurring object in the Procedure. For example, if the desire is to set a task event on the FinishTime of an object, but PreRelease is set to “(same as duration)” (i.e., default setting), FinishTime is not the actual end time of the object. It may be necessary to specify the StartTime or OnsetTime of the next occurring object as the Event. It is important to consider the timing properties of the object when defining task events.

Task events typically occur during time-critical portions of an experiment.  For this reason, the actions that may be defined are restricted. The following actions are prohibited within the action associated with a task event:

• Operations affecting the display (e.g., Canvas object commands)
• Sleep command
• Commands invoking another task event to start

In addition, if the task event specified requires a significant amount of time (e.g., extensive script segments), timing within the experiment may be affected. While a task event is processing, other events (including processing of input masks, painting of echo clients, termination of audio or movie playback, etc.) are blocked until the task event concludes. Therefore, events can be delayed, or potentially missed completely. For example, if a key is pressed during execution of a task event, echo of that input to the screen will be delayed until the task event terminates. To maintain accurate timing, task events should be brief, involving only essential actions, before returning to experiment execution. If extensive script is required in association with a task event, it is suggested that a Boolean value be set within the task event to trigger non-essential script at a later/non-critical time in the experiment outside of the task event, itself.
 
During experiment design, warnings of suspected timing errors will be reported by the Experiment Advisor within E-Studio’s Output window (refer to E-STUDIO: Experiment Advisor Window [22679] for additional information). Additionally, refer to the Experiment Advisor report for errors generated in the user interface or at runtime.  Errors will be generated in the case of each of the following:

• The specified script routine cannot be found or run
• Another task event is triggered
• Calls to Canvas.Copy (i.e., affects display)
• RteRunnableObject.Run is called
• Calls to StimDisplay.Draw (i.e., affects display)
• Calls to SlideVisualStim.Draw (i.e., affects display)
• Task Action routine or Parameter does not meet requirements

NOTE: The primary use of Task Events is to communicate with external devices through the passing of information from E-Prime to that external device. Task Events may also be used to process a signal sent from an external device to E-Prime when associated with one or more Task Events. Communicating with external equipment is accomplished through devices and input masks, which are then controlled using Task Events.

Device Task Events
Devices are external components that E-Prime can use to run an experiment. Devices can be used for multimedia and stimulus presentations, responses to stimuli, and flow control. Devices supporting Task Events within E-Prime include the ParallelPort, Serial, Port, Chronos, SRBox, Joystick, Keyboard, and Socket devices.

Script Task Events
E-Prime provides the ability to select user-written E-Basic script segments to be run as the Action of a Task Event.  User-written script routines are entered into an E-Prime experiment via the User Script window (see SCRIPTING: User Script Window [22879]).
 
User-written script routines must include one or two parameters, including “varname” As Context, and an optional second parameter. If a second parameter is specified, it is defined by the data type of the routine (i.e., Long, Integer, or String). Refer to E-STUDIO: Configuring Task Events [24789] for information pertaining to configuration of a parameter associated with a Script Task Event.
 
NOTE: Task events typically occur during time-critical portions of an experiment.  For this reason, the actions that may be defined are restricted, and if the task event specified requires a significant amount of time (e.g., extensive script segments), timing within the experiment may be affected. To maintain accurate timing, task events should be brief, involving only essential actions, before returning to experiment execution.If extensive script is required in association with a task event, it is suggested that a Boolean value be set within the task event to trigger non-essential script at a later/non-critical time in the experiment outside of the task event, itself. Refer to the above content concerning restrictions and timing associated with Task Events.
 
Define script routine
To specify a user-written script routine as the Action of a Task Event, first enter the script for the routine into the User Script window in the experiment. The image below illustrates entry of the EliminateOption routine in the User Script window within the ScriptTaskEvents sample experiment included in the E-Prime installation. This sample presents a choice reaction time experiment displaying a question with four response options. At designated times (i.e., delays), a Task Event calling the EliminateOption routine is triggered to disable the incorrect options, one at a time, until only the correct option remains.
 

 
The User Script in the ScriptTaskEvents sample experiment also includes the ClearAll routine for use in Task Events. The ClearAll routine resets the display options for the responses at the beginning of each trial. Note that the EliminateOption routine requires two parameters (i.e., c As Context, x As Integer), while the ClearAll routine requires only a single parameter (i.e., c As Context).
 
Add a Task Event
After the desired user-written script has been entered into the User Script window, it is available to be used within a Script Task Event. Next, add the desired Event that will be used to invoke the script via the Task Events tab on the appropriate object. Refer to E-STUDIO: Configuring Task Events [24789] for detailed instructions concerning adding and configuring a Task Event. 
 
Specify the Action
For a Script Task Event, the Action is selected from the script routines available in the experiment in User Script. In the Action field, use the dropdown menu to select from the available script routines. The image below illustrates the availability of the EliminateOption and ClearAll routines within the ScriptTaskEvents sample experiment.
 

 
If the routine requires a parameter other than varname As Context, the Parameter fields will be displayed, as shown in relation to selection of the EliminateOption routine in the image above.  If the routine does not require a second parameter, the Parameter fields are not displayed. As shown below for selection of the ClearAll routine.
 

 
Define the Parameter
Refer to E-STUDIO: Configuring Task Events [24789] for information pertaining to configuration of a parameter associated with a Script Task Event. When a script routine is selected as the Action for an event, and a parameter is required, the options for the fields available within the Parameter group will be determined by the definition of the routine within User Script.
 
Next Article: E-STUDIO: Configuring Task Events [24789]
Previous Article: E-STUDIO: Resources Folder [34542]