SCRIPTING: Examples and Exercises [22904]

Examples and Exercises

To begin adding user code, it is important to understand the basics of programming. The following examples illustrate the simplicity of E-Basic code. Be sure to follow through these examples before progressing to more advanced topics. It is recommended that each user actually implement each example, run it and verify that it works as expected before moving on to the next section. Some of the initial examples can be created in a blank E-Studio file; other examples involve modifications to one of the supplied sample experiment files. Specific instructions are provided for each section.

See the following articles for further information regarding the examples below:

SCRIPTING: Programming: Basic [25423]

SCRIPTING: Programming: Intermediate [22905]

SCRIPTING: Programming: Advanced [22909]

SCRIPTING: Context [22875]

OVERVIEW: Extending Experiments with Script [23286]

Example 1: Display “Hello World” on the screen
To run this example, create a new E-Studio experiment which has only an InLine object on the
SessionProc. The InLine object should contain the script provided below:

Example 2: Setting Attributes in the Context Object
The SetAttrib method is used to create an attribute and assign it a value. Specifically, the SetAttrib method is used to place the attribute in the context so that it may be assigned, modified, and referenced. In the example below, “c” has been defined as the Context object. This is done internally by E-Prime, and need not be explicitly entered into the script. The SetAttrib method is used in conjunction with the dot operator to declare TotalTrial as an attribute of the context object (“c”) and assign it a value of 10.

As with Example #1 above, to run this example you should create a new E-Studio experiment with an InLine object on the SessionProc and enter the script below.

Once an attribute is put into the context, the information is logged in the data file and the attribute may be used to display information by way of a display object (e.g., a TextDisplay).

The TotalTrial attribute will be available in the context during the scope of the level at which it has been defined. For example, if TotalTrial is defined (using SetAttrib) during the block level Procedure, it will be available during the context of the block level, and any context levels subordinate to the block (e.g., trial level, sub-trial, etc.). However, outside of that scope, the TotalTrial attribute value will not be available. There is no backward inheritance possible, which would allow higher levels to inherit attribute information from lower levels.

Figure 1. Inheritance within the Context flows from top level (Session) to lower levels (Block and Trial)

An attribute must be defined before it is referenced, or error messages will result indicating that the attribute does not exist. For example, if an attribute is defined at the trial level, and referenced at the block level (prior to the trial), an error will occur related to the declaration of the attribute.

The inheritance of the value to assign to an attribute follows the hierarchical structure, and values may only be inherited by levels lower than the level at which the attribute is defined. Thus, if an attribute is defined at the block level, it may be referenced at the trial or sub-trial level. Inheritance occurs in a downward direction, while the search for a value occurs in an upward direction. For example, if an attribute is defined at the block level and referenced at the trial level, the value at the trial level will be inherited from the block level (i.e., downward). The resolution of the value occurs by first searching the current level (i.e., trial), then continuing the search at the next highest level (e.g., block), and upward until the value is resolved.

Example 3: Getting Attributes from the Context Object
The GetAttrib method is used to retrieve a value for an existing attribute in the context. Like SetAttrib, the GetAttrib method is used in conjunction with the dot operator.

In the example below, the TextStimulus object displays a stimulus “X” or “Y.” In the script, the IF… THEN clause is used to evaluate the current stimulus and set its display color. The GetAttrib method will retrieve the value of the current stimulus. When GetAttrib returns a value of “X” the ForeColor property of the TextStimulus is set to “Green,” so that all X’s will be displayed in the color green. When GetAttrib returns a value of “Y,” the ForeColor property is set to “Blue” so that all Y’s will be displayed in the color blue.
 
To run this example, open the BasicRT sample experiment file, copy the script below into an InLine object placed at the beginning of the TrialProc, and run the experiment.

Example 4: Global Variables
Often, it is desirable or useful to determine the participant’s performance over the course of the experiment, or perhaps after a specified number of blocks or trials. One method of assessing performance is to use a FeedbackDisplay object, which can automatically calculate summary statistics (e.g., mean accuracy, mean RT, etc.). Another method of assessing performance involves the use of the Summation object. This method requires more involvement from the user, because user-written script is required, but it enables you to control precisely if and when the participant is presented with performance feedback. (i.e., While the FeedbackDisplay object performs all of the performance calculations automatically, it also presents feedback automatically). The example below uses a Summation object to determine average accuracy after a specified number of trials, but without presenting feedback to the participant. This example is illustrated within the BasicRT sample experiment file.

To use a Summation object to determine the average accuracy per condition or block, declare the Summation object on the User tab in the Script window. In most cases, accuracy would only be examined after a minimum number of trials. Thus, in order to start evaluating mean accuracy after a certain number of trials had been run, it be is also necessary to declare a counter to manually count the number of trials that have occurred. In the script below, the PracticeProp summation variable is declared for use in evaluation of the practice trial performance; the TrialCount integer variable is declared to keep track of the running trial count. Enter this script on the User tab in the Script window.

Once declared in the User Script window, the variables are available globally, or for the scope of the entire experiment. The variables must be initialized prior to the point in the experiment at which they are referenced. This is accomplished using an InLine object, inserted on the Session Procedure timeline. The InLine may occur at any point prior to the referencing of the variables. However, it is a good practice to insert the initialization InLine as the first event in the Session Procedure, which can serve to set up or initialize any variables that will be used. To continue with this example, add an InLine object named Setup as the first event on the SessionProc in the BasicRT sample experiment, and enter the script below:

The Set command is used to initialize the PracticeProp summation variable. This command defines the variable as a new instance of an existing object type. The TrialCount variable is initialized to zero since no trials have yet been run.

Once initialized, the variables may be assigned values and referenced within the context in which they were defined. In this case, the defined context was the top-level context (i.e., User tab at the experiment level). Thus, the variables are defined globally and may be referenced at any point in the program.

The script below illustrates how the Summation and counter variables are assigned values on each trial. The counter is manually incremented by one on each trial. The Summation variable collects accuracy statistics across trials during the entire block. In the BasicRT experiment, the responses are collected by the “Stimulus” object. Thus, the InLine that contains this script must follow the Stimulus object on the trial Procedure.  In the BasicRT experiment file, add an InLine object following the Stimulus object on the TrialProc, and enter the script below:

At five trials or more (i.e., TrialCount >=5), the mean of the values collected by the Summation is evaluated. If mean accuracy is greater than 80%, the currently running List (i.e., TrialList) is terminated. Thus, the script examines the overall accuracy of the block and terminates the block when a minimum accuracy of 80% is reached.

Note: Verify that the PreRelease property for the Stimulus object (on the Duration/Input tab of the Stimulus object Property Pages) is set to 0 to ensure that the InLine script is not processed prior to actually collecting a response to the stimulus.

Example 5: Trial Level Variables
Declaring global variables on the User tab of the script window permits the reference of these variables at any point in the experiment. Conversely, variables to be used only within a specific context (e.g., block or trial Procedure) may be declared using the Dim command in an InLine object on the appropriate Procedure. In the script below, the Dim command is used to declare a variable which collects a response on each trial. This script is entered in an InLine object, which is called from the trial-level Procedure object.

Example 6: Using Attribute References to Pass Information
Attributes allow the passing of variable information during a Procedure. List objects are used to organize data used within an experiment in attributes (see E-STUDIO: List Object [22700], and attribute values may be accessed using the c.GetAttrib command. The image below illustrates a List object defined within a basic Stroop task, in which the display color of the word varies per trial. The text stimuli (i.e., color words) and display colors (red, green, blue) are entered as values in the “Word” and “Color” attributes.

The values of the Word and Color (or other) attributes may be accessed in script using the c.GetAttrib command.  For example, the script below illustrates use of c.GetAttrib and Debug.Print to access the values on a specific trial and write them to the Output window (e.g., for monitoring selection during testing).

See Also:

SCRIPTING: Programming: Basic [25423]