E-Prime provides multiple tools to enable you to check the critical timing sequences in your experiment. Effective use of these tools, requires that you first understand the process by which E-Prime objects execute. You will then be able to understand the dependent variables corresponding to the steps in this process which you can choose to log in your data file.
The following articles illustrate the major steps in the execution of a series of E-Prime objects by examining an increasingly complex sequence of events, and then defines the variables that log the timestamps associated with these steps. The articles illustrate the tools that enable you to work with the variables of interest to confirm the timing of the critical experimental sequence.
A Simple Overview
An object’s execution occurs from its StartTime until its StopTime. OnsetTime is defined as the timestamp, in milliseconds, from the start of the experiment to when the object’s onset action, in this case drawing the display to the screen, begins. OffsetTime is defined as the timestamp, in milliseconds, from the start of the experiment to when the object’s offset action, in this case stop execution, begins. The duration of an object’s execution is the difference between the OffsetTime and the OnsetTime. Figure 1 below illustrates the TimeAudit variables for a single object executing in Event Mode.
Figure 1. Simplified timing diagram for an E-Prime Object
OnsetTime is a critical item to understand, so we’ll examine it a bit further here. For a display object, the OnsetTime provides a timestamp of the exact time at which the display object begins to draw. Monitors are always drawn starting with the upper left-hand corner of the monitor, and OnsetTime reflects this event. In other words, OnsetTime is the time immediately after the vertical refresh occurs and the draw command begins to execute. Note that this process describes how the monitor operates; E-Prime can also handle special situations where the video cards provide information in a different manner.
E-Prime can NOT tell you when each component of the display is placed on the screen. (Note that we are describing the typical behavior for CRT and LCD monitors; DLP and other styles of monitors may behave differently.) For example, consider a fixation cross in the center of the screen. If the monitor has a refresh rate of 60Hz, then it takes 16.6666ms for all of the pixels that comprise the display to have their information updated. In the case of a CRT display, this means refreshed with the electron gun; in the case of an LCD display, this typically means resetting the video hardware to prepare for the next set of data. Therefore, any information that is displayed in the center of the screen would appear approximately halfway through the screen update or approximately 8 ms after the object’s OnsetTime. As a final note about this simplified view of object execution, notice that the actual Duration that is shown in the figure is defined as the difference between the OffsetTime and the OnsetTime. This is NOT the same value that is logged in the data file as <object>.Duration. The Duration variable that is logged in the data file is the requested duration that is specified in the Duration field on the Duration/ Input tab. However, E-Prime provides an easy way to obtain a close approximation to how long a stimulus appeared on screen. The OnsetToOnset time, which indicates how much time elapsed from the Onset of the current object to the onset time of the next object, can be logged in the data file by utilizing the TimeAudit feature (but see TIMING: Time Audit: Confirming Accurate Timing  and TIMING: Time Audit  for important cautions regarding the interpretation of this value).
Object Execution: a more Complete Description
A more complete picture of object execution, reflecting important actions prior to an object’s OnsetTime, is shown in Figure 2. This example continues with Event Mode timing.
Figure 2. Event Mode with no PreRelease
Figure 2 introduces several new object properties: ActionDelay and ActionTime. As was stated above, the OnsetTime is the timestamp at which the object begins its action. For a visual display object, it represents the time at which the object begins to execute its draw command; for a SoundOut object, it is the time at which the object begins to play the sound file. More precisely, the OnsetTime represents the timestamp at which E-Prime passes off execution for stimulus presentation to the appropriate hardware’s drivers (e.g. the video or sound card) and to the operating system. The ActionTime represents the timestamp at which the hardware’s driver returns control back to E-Prime.
Typically, the difference between the OnsetTime and the ActionTime will be less than 1 millisecond. Any cases where they are not within a millisecond of each other may signal a potential problem with your hardware device. Therefore, when you check your pilot data, include an evaluation of ActionDelay, to ensure that no significant delays are occurring.
OnsetDelay and TargetOnsetTime: OnsetDelay is the difference between the TargetOnsetTime and the OnsetTime. The TargetOnsetTime is a timestamp calculated internally by E-Prime at the conclusion of the prior object. With a discrete trial paradigm, OnsetDelay should be as small as possible1.
1In some cases, OnsetDelay can be negative. This can occur when using RefreshAlignment. See TIMING: Obtaining Accurate Timing and Timing Best Practices 
Object.GeneratePreRun and Object.GeneratePostRun Property
E-Prime provides the GeneratePreRun and GeneratePostRun properties (Common tab) to define when object resources are loaded. When these properties are set to TopOfProcedure, the .Load script generated by E-Studio will occur at the start of the Procedure. This provides the benefit of having all of the objects load their properties at a non- time critical portion of an experiment. Use of the BeforeObjectRun setting results in the script for .Load being generated immediately prior to the .Run script generation for an object.
Objects on a Procedure may individually select this property setting, or the Inherit (default) setting results in inheritance of the property setting from the Procedure. Using Inherit for the property setting permits for easier changing of all object behavior on a Procedure by setting the desired script generation only on the Procedure.
NOTE: When using the TopOfProcedure option in the GeneratePreRun field, [attrib] references for any properties on the objects that are modified by c.SetAttrib calls on the Procedure will update the value of the attribute in the Context, but updates will not be reflected in the Procedure (i.e., because .Load operation for the object has already occurred). To update properties during a Procedure using attribute references, set the GeneratePreRun field to BeforeObjectRun.
Next Article: TIMING: Operating System Solutions 
Previous Article: TIMING: Stimulus Presentation Challenges 
Legacy End User Comments
|A couple more "gotchas" with GeneratePreRun: |
- TopOfProcedure works only when all stimulus settings & content are known at the start of the Procedure; if stimulus settings or content depend on earlier outcomes or attributes within the Procedure, then use BeforeObjectRun.
- TopOfProcedure may interfere with Movie or Sound objects at the end of Procedures -- e.g., with PreRelease set to "(same as duration)", the next file will load and halt playback of the current file. For this case, set GeneratePreRun of stimulus or Procedure to BeforeObjectRun, or set PreRelease to 0.
|Any details on what exactly GeneratePostRun does? I tried changing this from AfterObjectRun to EndOfProcedure and could not find any difference (even the .ebs2 file size remained the same). Also, could you provide a use-cases for these options? Thanks.|
|For helpful hints with when to use or not use TopOfProcedure please see http://www.pstnet.com/support/kb.asp?TopicID=2627 |
There is currently no specific usage for GeneratePostRun and is implemented as a balance for the mirror of GeneratePreRun. While nothing uses it, the ability to do so could be taken advantage of with the use of a PackageFile epk2 file and PackageCall objects.
|The notation "Object.GeneratePreRun", etc., implies that these are available as properties of certain objects, but this would be wrong. Objects have no GeneratePreRun or GeneratePostRun properties, and trying to use such a property with inline code will result in a compile-time error. |
Rather, Generate PreRun (and PostRun) are flags on the Property Pages of certain objects in E-Studio, and they act as directives to the code generator to generate additional E-Basic code to provide the function described above.
|Yet more "gotchas" with GeneratePreRun: |
- TopOfProcedure may also affect duration of sound recordings when using SoundIn or SlideSoundIn, similar to how it may affect Movie and SoundOut objects (as described earlier).
- As said in different words in the main article, when using TopOfProcedure, objects that rely on "" attribute references may fail if any of those attributes are created from inline code within the Procedure, because code that uses those attributes for the objects may try to run before the inline code that creates the attributes (e.g., http://www.pstnet.com/forum/Topic8792-12-1.aspx).
Please sign in to leave a comment.