The following steps contain helpful information for writing E-Basic script or accessing values determined through script:
1) Determine the Purpose and Placement of the Script
The user must consider what task the script is supposed to accomplish and when the action must occur. For example, an experimenter might want to choose a random number from 1-499 to be used as the stimulus display for each trial. The purpose of the script, therefore, is to select a random number and to place the selected value into a form usable by E-Prime.
The placement of the script must be within the Procedure driving the events of the trial. Specifically, since the random number is to be used during the display of the stimulus, the script determining the value must be entered in the trial Procedure prior to the object displaying the stimulus.
2) Create an InLine Object and Enter the Script
Once the appropriate placement of the script has been determined, create an InLine object at that location. If the script is to determine a random number during the trial Procedure (TrialProc) prior to the stimulus display, the most appropriate location for the InLine object containing this script is as the first event in the TrialProc.
Actually, any time prior to the event displaying the stimulus would be appropriate, but it is good practice to separate the setup events from the critical events of the trial (e.g., Fixation-Stimulus-Feedback). It is also good programming practice to apply useful names to the user-created InLine objects. In this example, the default name of InLine1 has been changed to the more meaningful GetRndNum.
After placing an InLine object in the appropriate location, double click the InLine object to open it, and enter the script required to accomplish the task. To select a random number (1-499), and to place the selected value into a form usable by E-Prime 3.0, enter the following script.
The Random function is used to select a random value from 1-499, and the SetAttrib command is used to place that value into an attribute for later access. Notice the single quote character used to enter a comment in the script above. The single quote character is used to skip all characters between the apostrophe and the end of the current line. An alternative method to create comments is with the Rem statement (for “remark”). Refer to the Comments topic on the Contents tab (listed under E-Prime Command Reference) for more information.
3) Determine the scope of variables and attributes
Variables or attributes declared within an E-Prime experiment are limited to the scope of the Procedure in which they are defined. Variables to be used only during a single trial may be declared and initialized at the trial level. For example, a variable used as a counter may be declared locally, as in the following example:
When InitializeArray is placed in the trial Procedure, both “i” and “arrValue” will be accessible during the trial. At the end of the trial Procedure, the “i” and “arrValue” variables will be discarded (e.g., the value of arrValue will not be accessible by an event at the block level).
If a variable is to be maintained or accessed across multiple executions of a Procedure (e.g., performance over a series of blocks), the variable must be declared globally in the User Script window. For example, a variable might be declared to keep track of the total number of trials. Use the View menu to display the User Script window in E-Studio and to declare a global variable.
Initialization of global variables cannot occur in the User Script window; instead, an InLine object would be used for this purpose. To initialize a global variable prior to its use (e.g., to initialize the number of trials to 0), use an InLine object placed appropriately. It is a good practice to initialize variInIables as the first event in the Procedure in which they will be used as part of the Procedure setup events. In this case, global variables exist throughout the scope of the experiment, so initialization should take place as the first event in the Session Procedure.
The global variable may then be updated during the trial level Procedure to maintain a count across multiple executions of the Procedure. To use the global variable to update the trial count, insert an InLine object as the first event in the trial Procedure, and enter script to increase the count.
The total trial count variable is updated simply by increasing the previous value by one (i.e., g_nTotalTrial+1). The second line of script referring to the c.SetAttrib command is used to place the value of g_nTotalTrial into an attribute (to make it accessible by other objects with the bracket notation and to log the value in the data file.
4) Set or Reference Values in Script
If variables are to be retrieved and/or logged, they must be placed into the experimental context as attributes. Otherwise, they exist only temporarily, and are discarded at the conclusion of the Procedure in which they are defined. Globally defined variables, created in the User Script window, are discarded when the Experiment Object terminates.
Attributes defined in a List object are automatically placed into the experimental context. For example, if a List object defines an attribute named “Stimulus ,” and the values of Stimulus are used to define the stimulus displayed during each trial, the value of Stimulus for each trial will automatically be logged in the data file.
In order to enter a temporary variable (e.g., g_nTotalTrial from the previous step) into the experimental context, either for the purpose of logging that value in the data file or for later access by another object, use the c.SetAttrib command. In the previous step, the value of the g_nTotalTrial variable was set as an attribute (i.e., c.SetAttrib “TrialCount,” g_nTotalTrial). The TrialCount attribute may then be accessed by another object using bracket notation, and the value of TrialCount will be logged in the data file.
The values of attributes and properties from the experimental context may also be accessed via script on an InLine object using the c.GetAttrib command. For example, the stimulus might display a random number selected from a range of values depending on the condition. “Condition” could be entered as a List attribute defining the possible conditions, and this value could be retrieved at runtime to set the possible range of values for the random number selection.
NOTE: The use of the “Else” condition in the script above. It is a good practice, and ultimately the programmer’s responsibility, to cover all possible conditions when writing script. If the values of the Condition attribute are carefully entered, the “Else” condition should not be necessary. However, it is better to consider the possibility of error than to have the program fail. Here, we put up a message box to tell the experimenter a bad stimulus condition has occurred.
The properties of objects may also be set or retrieved through script as long as the property is not read- only or design-time only (i.e., not able to be modified at runtime). For example, it is possible to vary messages presented at runtime based on the speed of the response collected. Such a procedure would require accessing one value (i.e., the reaction time from the input object Stimulus.RT), and setting another (i.e., the text to be displayed by the object presenting the message).
The GiveRTFeedback Inline object containing the script above sets the Text field for the WorkFaster TextDisplay object at runtime. Thus, no values need be entered for the Text field in the WorkFaster object in E-Studio.
5) Reference Script Results from other Objects
After a variable has been entered into the experimental context as an attribute, that attribute may then be accessed by other E-Prime objects occurring within the same scope. For example, once the random value has been set as an attribute at the beginning of the trial Procedure, that attribute may be referenced by a TextDisplay object in order to display the value as the stimulus during the trial. To refer to an attribute, use square brackets surrounding the attribute name (e.g., [Stim]) in the Text field of the TextDisplay object.
NOTE: Most properties of E-Studio objects may be changed through script as well. For example, to change the location of the display area defined by a TextDisplay object, the X property for a TextDisplay object named TextDisplay1 could be set as TextDisplay1.X = 100. This command sets the horizontal location of the display area to begin at pixel location 100.
Debug commands are useful in tracking down problems, verifying values, or simply reviewing the execution of the program. The Debug object, when used with the Print method, is used to send information at runtime to the Debug tab of the Output window for examination following the run. For example, the following script could be used to write the value of the Stimulus attribute to the Debug tab in the Output window during each trial.
The script above will send the value of the Stimulus attribute per trial to the Debug tab in the Output window. After the run, the Debug output may be viewed by displaying the Output window within E-Studio. If the Output window is not displayed by default, select Output from the View menu. Then, in the Output window, select the Debug tab.
Debug.Print may also be used to monitor timing and response events. The following script uses Debug.Print to write the stimulus onset time and the participant’s response to the Output window.
The contents of the Debug tab may be copied to the clipboard by first selecting the lines of information in the Debug tag that are of interest and then right clicking in the Output window. Then, the Debug output may be pasted into Excel (or another application)hh to print it or use spreadsheet calculations to check the timing of events.
The Debug object is most appropriate during the development and testing of new programs. After an experiment has been fully tested, the Debug commands may be disabled by setting the Debug object’s Enabled property to “false” (i.e., Debug.Enabled = false). This allows the user to leave Debug commands in the script for future testing purposes, but to improve the efficiency of the program during data collection.
A final method of debugging involves the use of comments to indicate the purpose of certain sections of script. This method may be employed more often as a preventative measure than as a diagnostic tool, but can be of tremendous importance during debugging (especially if someone other than the author of the script is given the task of debugging). There is no standard style for adding comments, but in general they should be brief descriptions of the purpose of the segment of script. Many of the script examples used in this chapter make use of brief comments to summarize the purpose of the script for the reader. In E-Basic, comments are separated from script that is generated through the use of the apostrophe (‘) keyword or the Rem statement. Refer to the E-Prime Command Reference for further discussion of comments.
After the experiment is functioning without errors, it is important to completely test it prior to running participants. The Debug object is especially useful for testing an experiment. Use the Debug.Print command to send variable values to the Output window, and keep track of the progress of the experiment with a pencil and paper as well.
After running the experiment, examine the output on the Debug tab to view the values. Alternatively, the contents of the Debug tab may be copied to the clipboard and pasted into another application for more thorough viewing or analysis. A written-record and the Debug output should be compared to the data file to verify that all of the variables are being logged, the values are in the correct range, and the sampling is occurring as expected. It is important to test the script completely, including tests of unlikely responses and invalid ranges.
Previous Article: SCRIPTING: User Script Window