Mastering E-Prime: Meaning of all time audit measures.

[David McFarlane]

When you look at the Logging tab on the properties page of any
stimulus object, you will find a host of items available for
logging. Most of these are time audit data. But what do all these
items mean, and what are they good for? Chapter 3 of the E-Prime
User's Guide discusses time auditing to some degree, and the timing
diagram at Appendix E provides one way to see the relationships
between these items. As an alternative, here I try to set out, in
order, a brief description of these items.

First let us distinguish between timing control *settings* and time
audit *measures*. The following items do not reflect any results
formed during the course of a stimulus but simply log the settings
provided by the user (e.g., you). You may choose to have any of
these logged just to keep a record of settings active during the experiment:
- Duration: To reiterate, this does *not* show the actual duration of
the stimulus, only the setting as provided by the user.
- PreRelease: Affects the TargetOffsetTime (see below).
- TimingMode: Event, Cumulative, or Custom, as set by the user (see
the online E-Basic Help).
- CustomOffsetTime: In Custom timing mode, overrides the
TargetOnsetTime (see the online E-Basic Help).
- CustomOnsetTime: In Custom timing mode, overrides the
TargetOffsetTime (see the online E-Basic Help).

Now, the raw time audit measures, listed in the order in which events
occur during the execution of a stimulus object. These are all time
stamps in milliseconds from the start of the current program run:
- StartTime: Time at which E-Prime started executing the stimulus
object.
- TargetOnsetTime: Scheduled time at which presentation of stimulus was
to begin; set automatically from GetNextTargetOnsetTime (see online
E-Basic Help).
- OnsetTime: Time when E-Prime actually submitted the stimulus data for
presentation (e.g., proceeded to copy data to display memory or load
sound buffer). This may not coincide with when the stimulus actually
got presented, e.g., if data are submitted in the middle of a display
refresh cycle then they may not get presented until the next refresh.
- ActionTime: According to the online E-Basic Help, time at which
E-Prime completed the "critical action" of the stimulus. The
documentation remains somewhat vague about this -- perhaps "critical
action" means copying data to display memory, or loading a sound or
video buffer. In my tests, ActionTime never lags more than 1 ms
behind OnsetTime, so it serves practically the same purpose as
OnsetTime.
- TargetOffsetTime: Scheduled time at which offset actions (e.g.,
clean-up, ClearAfter, StopAfter) of stimulus object were to begin,
e.g., OnsetTime + Duration - PreRelease (Event timing mode), or
TargetOnsetTime + Duration - PreRelease (Cumulative timing mode).
- OffsetTime: Time when E-Prime actually began the offset actions of
the object. Actions may not take practical effect until next
vertical blank, or until presentation of next stimulus.
- FinishTime: Time when E-Prime exited from execution of the
stimulus object and proceeded to execute the next section of the
program (e.g., next stimulus object or inline code). Note that
*execution* of a stimulus *object* may end before *presentation* of
the *stimulus* ends; this is the point of PreRelease (as well as
happening as a matter of course with some stimuli such as some
sounds).

Finally, a few composite time audit measures derived from the raw
measures above and provided for convenience:
- OnsetDelay = OnsetTime - TargetOnsetTime
- ActionDelay = ActionTime - OnsetTime
- OffsetDelay = OffsetTime - TargetOffsetTime
- DurationError = OffsetTime + PreRelease - OnsetTime - Duration

Note:
- Time audit measures include the ActionTime that follows upon
OnsetTime, but no corresponding item to follow upon OffsetTime.
- No time audit item for time stamp of vertical blank, although many
stimuli do not take full effect until just after a vertical blank.

-- David McFarlane, Professional Faultfinder

[David McFarlane]

I worked on getting that little write-up done exactly right for at
least a week, and after posting it still find things to revise; in
particular, looking back at the E-Prime Reference Guide, I concede
that the documention was not quite as vague about "Critical Action"
as I stated (but I still had to do my own tests in E-Prime to clarify this).

Anyway, I should have closed with a list of references, so here it is:

References:
- E-Prime User's Guide, Chapter 3 & Appendix E.
- E-Prime Reference Guide, section 1.3.1.4 Logging Tab.
- E-Basic online help, topic "Time Audit".

[justine]

I am in the process of conducting my own timing tests (for an Eprime/NetStation experiment), and this was invaluable in trying to understand the time audit measures. I gather from this that there is no way of knowing when the stimulus was *actually* presented on the screen (given the refresh rate). I assume this means that my triggers in the EEG record could be off by whatever that screen refresh delay was. Is that correct?

Thanks,

Justine VanDyke
Postdoctoral Research Fellow
University of South Carolina

[David McFarlane]

Justine,

No programming system can exactly control the actual onset time of
stimuli, due to the nature and limitations of stimulus hardware. For
visual stimuli in particular, the video frame rate plays one limiting
role -- please see the "Critical Timing" chapter in the User's Guide
that came with E-Prime (and/or take my online video course, see link below).

If one wished merely to *know* when a visual stimulus got presented
(as distinct from *controlling* its onset time), one might use the
output of a high-speed photodector aimed at a choice spot on the
display. Technically speaking, even then the time of stimulus
presentation to the subject depends on things such as the distance
from the display to the subject, the speed of light, photoreceptor
response rates, nerve conduction to visual cortex, etc. So the real
question becomes, just how accurately do you need to control or know
the onset time, and can we make it "good enough"?

And here we have some hope. If you synchronize your visual stimuli
to start with the "vertical blank", then stimulus OnsetTime should
correspond very closely to when the system starts writing the
stimulus screen to the top of the display -- and starting with
EP2.0.10.182, you can even adjust this (see
http://www.pstnet.com/support/kb.asp?TopicID=3027 ). Now you just
need to synchronize your EEG signals with the OnsetTime of your
stimulus. As you have no doubt figured out, you will be hard pressed
to do that using WritePort. But OnsetSignalEnabled, etc., do just
what you need here (please see
"RteRunnableInputObject.OnsetSignalEnabled" and related topics in the
E-Basic Help facility). And with EP2.0.10.182 and later you may
accomplish the same end with the new Task Events feature, which
should supplant OnsetSignal..., etc. (I show how to use
OnsetSignal... to output EEG signals in my online video course, and
hope to include coverage of Task Events in the future.)

Finally, if you want to verify that your EEG triggers really are
synchronized with your stimuli, then you should use an oscilloscope
to monitor both the stimulus onset and the EEG trigger (the Black Box
ToolKit may may this easier).

I hope that helps.

-----
David McFarlane
E-Prime training
online: http://psychology.msu.edu/Workshops_Courses/eprime.aspx
Twitter: @EPrimeMaster (https://twitter.com/EPrimeMaster)

[David McFarlane]

Justine,

I should mention that using OnsetSignal... still entails some
"gotchas" (which I go over in the course).

-- David McFarlane

>--
>You received this message because you are subscribed to the Google
>Groups "E-Prime" group.
>To unsubscribe from this group and stop receiving emails from it,
>send an email to e-prime+u...@googlegroups.com.
>To post to this group, send email to e-p...@googlegroups.com.
>For more options, visit https://groups.google.com/groups/opt_out.
>

[Sylvain]

Hi David,

I have a question regarding to pre-release and timing.

I did a little experiment trying to get the timestamp of the onset of stim, and the offset or it.

It's simple basically i have :

- Inline1: I collect t1 = Clock.ReadMillisec

- Then an ImageDiplay for 200 ms with a pre-realase equal to the duration of it. I log the onset of ImageDiplay and the offset of it;

- Inline 2: I collect t2 = Clock.ReadMillisec

Doing that, basically I get t2-t1 almost equal to 0 modulo some refresh rates.

I also get ImageDiplay.OnsetTime = ImageDiplay.OffsetTime.

1) There's something there that I don't really understand, which timestamp should I really consider,  ImageDiplay.OnsetTime or ImageDiplay.OffsetTime?

2) If I understood pre-realase affect offset time, so does that mean that:

ImageDiplay.Duration = (ImageDiplay.OffsetTime -  ImageDiplay.OnsetTime) + pre-realase

3) The fact that Inline2 is executed at the same time as Inline1 is particulary disturbing for me. Does that mean than Inline placed after an object could be executed while this object is still on screen?

Thank you for any answer, I'm confused about this!

Sylvain

[David McFarlane]

Sylvain,

At 2/22/2013 06:36 AM Friday, Sylvain wrote:
>Hi David,
>
>I have a question regarding to pre-release and timing.
>
>I did a little experiment trying to get the timestamp of the onset
>of stim, and the offset or it.

Wonderful, everyone should do these sorts of explorations (that's how
I figured out all this stuff).

>It's simple basically i have :
>
>- Inline1: I collect t1 = Clock.ReadMillisec
>- Then an ImageDiplay for 200 ms with a pre-realase equal to the
>duration of it. I log the onset of ImageDiplay and the offset of it;
>- Inline 2: I collect t2 = Clock.ReadMillisec
>
>Doing that, basically I get t2-t1 almost equal to 0 modulo some refresh rates.
>I also get ImageDiplay.OnsetTime = ImageDiplay.OffsetTime.

As you should. You might find OffsetTime slightly behind OnsetTime;
and under these conditions (PreRelease = Duration), you should find
that TargetOffsetTime = TargetOnsetTime without exception.

>1) There's something there that I don't really understand, which
>timestamp should I really consider, ImageDiplay.OnsetTime or
>ImageDiplay.OffsetTime?

That depends entirely on what you wish to do with that timestamp.

>2) If I understood pre-realase affect offset time, so does that mean that:
>ImageDiplay.Duration = (ImageDiplay.OffsetTime
>- ImageDiplay.OnsetTime) + pre-realase

Not quite -- E-Prime can control only *Target* offset (& onset)
times, not actual times. Actual offset (& onset) times are subject
to the limitations of the stimulus presentation hardware. Also, I
would not write the relationship that way -- that makes it sound like
Duration derives from the other quantities, which is wrong. As I
described earlier, Duration remains whatever you asked it to be, so
should appear only on the right side of the equals sign as it is used
to determine other quantities. Thus, repeating what I wrote in my
earlier description of TargetOffsetTime, in the case of Event timing mode,

ImageDisplay.TargetOffsetTime = ImageDisplay.OnsetTime +
ImageDisplay.Duration - ImageDisplay.PreRelease

Note that, in the case PreRelease = Duration (the new default setting
since EP2.0.10.x), we get simply

ImageDisplay.TargetOffsetTime = ImageDisplay.OnsetTime

which fits your observations. If instead we set PreRelease to 0, we find

ImageDisplay.TargetOffsetTime = ImageDisplay.OnsetTime +
ImageDisplay.Duration

which perhaps is what you expected (and was the default for Event
timing mode prior to EP2.0.10.x).

And just to drive the point further, OffsetTime does *not* indicate
the time at which *presentation* of a stimulus ends. Rather, (for
most practical purposes) it indicates when *execution* of the
stimulus Run method ends (strictly speaking, this describes
FinishTime, see my earlier description for the fine distinction
between OffsetTime and FinishTime).

Furthermore, even with PreRelease set to 0, neither Duration nor
(OffsetTime - OnsetTime) necessarily indicate the actual duration of
the stimulus. In particular, a visual stimulus does not disappear at
its OffsetTime (ignoring Clear After, which has been deprecated), but
remains visible until replaced by another visual stimulus, so actual
presentation duration is

Stim2.OnsetTime - Stim1.OnsetTime

and EP2.0.10.x Pro can now log those values for you
(http://www.pstnet.com/support/kb.asp?TopicID=718 )!

>3) The fact that Inline2 is executed at the same time as Inline1 is
>particulary disturbing for me. Does that mean than Inline placed
>after an object could be executed while this object is still on screen?

Yes, and that is exactly what we want it to do in many, many cases
(e.g., to handle multiple mouse actions while a visual stimulus
remains on the display, or to prepare the next stimulus during the
run of the current stimulus). If you really want your InLine to wait
until the previous object completes its Duration, then set PreRelease
of that object to 0.

Hope that helps,

-----
David McFarlane
E-Prime training
online: http://psychology.msu.edu/Workshops_Courses/eprime.aspx
Twitter: @EPrimeMaster (https://twitter.com/EPrimeMaster)

>--
>You received this message because you are subscribed to the Google
>Groups "E-Prime" group.
>To unsubscribe from this group and stop receiving emails from it,
>send an email to e-prime+u...@googlegroups.com.
>To post to this group, send email to e-p...@googlegroups.com.

>To view this discussion on the web visit
><https://groups.google.com/d/msg/e-prime/-/eFwpjTnxC2kJ>https://groups.google.com/d/msg/e-prime/-/eFwpjTnxC2kJ.
>For more options, visit
><https://groups.google.com/groups/opt_out>https://groups.google.com/groups/opt_out.
>
>

[David McFarlane]

Slight correction -- logging of OnsetToOnsetTimes works for both
"Standard" (i.e., base) and Professional editions of EP2.0.10.x.

-- David McFarlane

[Scott]

Thanks for warning us, David. I've used OnsetSignal for years, assuming it worked as advertised (after checking critical OTO intervals during test runs by comparing triggers in CNT files with corresponding onsets times in Edat files).  I'm also surprised to hear that Task Events supplant using OnsetSignal. When I asked, Eprime support was not able to demonstrate how Task Events could replicate what I'm accustomed to doing with OnsetSignal, to code and distinguish stimuli in EEG recordings. If Task Events can really do the same things better, then I should reconsider my methods (of programming and Epoching) and adapt to using Task Events instead, now that I've finally adopted the Production Resease.  I've been slow and cautious to change, and only recently started programming new experiments with E-Prime 2.0.10.262..  -- Scott

[Scott]

Sorry -- After reviewing the revised task from support, I see Task Events CAN (apparently) send an onset code AND rest the port after 10 ms (or whatever). What this support example failed to do (and what I'd hoped Task Events could do) is replace inline code used to send conditional response codes. Otherwise, Task Events does seem able to send any specific code, that's available as an attribute. But even this ability seems less flexible than how I can select from several attributes specific ones as onsetSignalData for different objects at the beginning of each trial. However, this sample from support might not take advantage of all options for Task Events, so I should study the documentation more before dismissing it. I admit I haven't give Task Events a fair chance, after being disappointed about it's (apparent) limitations for sending conditional response codes.

[Sylvain]

David and Scott,

Thank you for your answers. I need to be reassured. When doing EEG experiment, I always run an inline before the object I want to trigger(maybe I could even do that at the top of the procedure I guess). Let's call this object StimEEGa,d the trigger 50.

What I always did was an inline like:

StimEEG.OnsetSignalEnabled = True

StimEEG.OnsetSignalPort = &H378

StimEEG.OnsetSignalData = 50

StimEEG.OffsetSignalEnabled = True

StimEEG.OffsetSignalPort = &H378

StimEEG.OffsetSignalData = 50

If I understand correctly This inline tell "wait for the object StimEEG to run and send the signal'. By running I mean waiting for StimEEG to be drawn on the screen right, independantly of any pre-release ? On the e-prime side, does this correspond to StimEEG.OnsetTime?

Thank you,

Sylvain

[David McFarlane]

Scott,

Ah yes, conditional *response* codes, that is an entirely different
matter from what Justine & I were discussing. I too hoped that Task
Events would handle conditional response codes, but alas, no. So for
that, yes, we still need to use WritePort or the like in inline code,
and it takes considerable coding finesse to get it to do just what we
want, more than we can go into here (see, e.g., discussions at
https://groups.google.com/d/topic/e-prime/z8PQMH1cf70 and
https://groups.google.com/d/topic/e-prime/7w5ajYuHqgw , as well as
several Knowledge Base articles about sending signals to external equipment).

But back to outputting signals coincident with *stimulus* onset. As
you mentioned, resetting signals at a delay after outputting them is
just one of the "gotchas" that I referred to, and Task Events handles
that very nicely. As for *conditional* stimulus codes, as you
mention, Task Events can use attribute references for the output
data, and that seems no different to me from what you can do with
OnsetSignalData (but without requiring inline code). Did I miss something?

BTW, when I said that Task Events should supplant OnsetSignal..., I
merely meant that we users should oursleves over time abandon
OnsetSignal... in favor of Task Events, which does everything that
OnsetSignal does now, only more and better. I did not mean that PST
has any evident plans to stop support for OnsetSignal, so my
apologies to anyone who felt alarm over the way I stated that. I
suppose that users who prefer OnsetSignal may continue to do so for
the foreseable future. (And note that Task Events works only with
EP2 Pro files.)

-----
David McFarlane
E-Prime training
online: http://psychology.msu.edu/Workshops_Courses/eprime.aspx
Twitter: @EPrimeMaster (https://twitter.com/EPrimeMaster)

> ><http://www.pstnet.com/support/kb.asp?TopicID=3027>http://www.pstne

> t.com/support/kb.asp?TopicID=3027 ). Now you just
> >need to synchronize your EEG signals with the OnsetTime of your
> >stimulus. As you have no doubt figured out, you will be hard
> >pressed to do that using WritePort. But OnsetSignalEnabled, etc.,
> >do just what you need here (please see
> >"RteRunnableInputObject.OnsetSignalEnabled" and related topics in
> >the E-Basic Help facility). And with EP2.0.10.182 and later you may
> >accomplish the same end with the new Task Events feature, which
> >should supplant OnsetSignal..., etc. (I show how to use
> >OnsetSignal... to output EEG signals in my online video course, and
> >hope to include coverage of Task Events in the future.)
> >
> >Finally, if you want to verify that your EEG triggers really are
> >synchronized with your stimuli, then you should use an oscilloscope
> >to monitor both the stimulus onset and the EEG trigger (the Black
> >Box ToolKit may may this easier).
> >
> >I hope that helps.
> >
> >-----
> >David McFarlane
> >E-Prime training
> >online:

> <http://psychology.msu.edu/Workshops_Courses/eprime.aspx>http://psychology.msu.edu/Workshops_Courses/eprime.aspx
>
> >Twitter: @EPrimeMaster
> (<https://twitter.com/EPrimeMaster>https://twitter.com/EPrimeMaster)

[David McFarlane]

Sylvain,

Yes, as far as I understand, OnsetSignal should coincide with
OnsetTime -- in fact, a Knowledge Base article says just that
(http://www.pstnet.com/support/kb.asp?TopicID=1318 ). But you should
not take anyone's word for that, not even mine (and certainly not
PST's). You should test that for yourself with an oscilloscope or a
Black Box ToolKit. Or if you want to have E-Prime test itself, and
you have a parallel port that will both output and input data, you
may try the following hack: Set up a PortDevice at the parallel
port, and use OnsetSignal with the same parallel port. Then get the
timestamp of OnsetSignal from the History of the PortDevice (no, you
do not need an input mask, and yes, this is advanced E-Prime
hacking), and see if that matches OnsetTime. I have used this hack
myself to explore E-Prime's input mechanisms, but have not used this
to explore OnsetSignal, and I did that hack with E-Prime 1.2 and an
older laptop so don't know if the hack still works on later
systems. Finally, if you have EP2.0.10.x or later (Pro only), then
you should explore using Task Events instead of OnsetSignal, etc.

That said, two comments on your code example:

1) Because your SignalData never changes, yes, you could put that
code at the top the Procedure, or better yet, at the top of
SessionProc (that is what I would do) -- it only needs to run once
for the entire session, no need re-running it each time before the
stimulus. But I understand it may make the program easier to read by
putting this action before the stimulus, and that has some value (so
when I put OnsetSignal code up in SessionProc, down in the Procedure
I still add an InLine just with comments to explain what I did).

2) Should your line

StimEEG.OffsetSignalData = 50

read instead

StimEEG.OffsetSignalData = 0

? I.e., don't you want to use OffsetSignal to reset the signal so
that the OnsetSignal will work the next time around?

Regards,

-----
David McFarlane
E-Prime training
online: http://psychology.msu.edu/Workshops_Courses/eprime.aspx
Twitter: @EPrimeMaster (https://twitter.com/EPrimeMaster)

>(<http://www.pstnet.com/support/kb.asp?TopicID=718>http://www.pstnet.com/support/kb.asp?TopicID=718

>)!
>
>
> >3) The fact that Inline2 is executed at the same time as Inline1 is
> >particulary disturbing for me. Does that mean than Inline placed
> >after an object could be executed while this object is still on screen?
>
>Yes, and that is exactly what we want it to do in many, many cases
>(e.g., to handle multiple mouse actions while a visual stimulus
>remains on the display, or to prepare the next stimulus during the
>run of the current stimulus). If you really want your InLine to wait
>until the previous object completes its Duration, then set PreRelease
>of that object to 0.
>
>Hope that helps,
>-----
>David McFarlane
>E-Prime training
>online:

><http://psychology.msu.edu/Workshops_Courses/eprime.aspx>http://psychology.msu.edu/Workshops_Courses/eprime.aspx
>
>Twitter: @EPrimeMaster

>(<https://twitter.com/EPrimeMaster>https://twitter.com/EPrimeMaster)

[David McFarlane]

As long as this thread has been reopened, I might as well mention
that EP2.0.10.x adds more time auditing measures (including, e.g.,
OnsetToOnsetTime!), so this report needs updating if it is to really
include "all" time audit measures. Don't know when I will get around
to that myself.

-----
David McFarlane
E-Prime training
online: http://psychology.msu.edu/Workshops_Courses/eprime.aspx
Twitter: @EPrimeMaster (https://twitter.com/EPrimeMaster)

[Justine VanDyke]

Hello,

I really appreciate all the information.

After conducting a timing test, we find a consistent ~16 ms lag on the EPRime/Screen presentation. It's possibly the result of the HDMI conversion in the display monitor. Because the lag is completely consistent across all trials, I assume that this is not particularly problematic with regard to my EEG signals (for my purposes at least). However, we may try a VGA cable to see if we can improve this delay in future.

In the meantime, I appreciate the information about the Task Events feature and also the information about the EPrime programming course, which I am going to look into.

Thanks! Justine

--
You received this message because you are subscribed to the Google Groups "E-Prime" group.

To unsubscribe from this group and stop receiving emails from it, send an email to e-prime+unsubscribe@googlegroups.com.

To post to this group, send email to e-p...@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

[Scott]

Perhaps I should start another thread about Task Events rather continue this topic here. However, I want to respond to David' post, to followup, clarify, and correct some information I posted earlier comparing the use of Task Events vs OnsetSignalData..

You're correct, David, "..Task Events can use attribute references for the output data, ..." and that is no different what you can do with OnsetSignalData. It just doesn't add much, if anything, at least for ERP paradigms that we tend to use, EXCEPT for a convenient way to reset the port after you've sent a signal. At the same time, PST missed a golden opportunity to add a significant MISSING feature, something that CANNOT be accomplished with OnsetSignals, by not implementing conditional response codes for Task Events. That said, I admit that I'm ready to try my first ERP experiment with Task Events instead of onsetSignal commands. In our lab, we already do post-processing of event codes, rearranging the codes into trials by paring each stimulus event code with a response code. With a (hopefully) minor teak to the program used for that step, I plan to switch each of the conditional response codes (sent via WritePort AFTER each trial), with the static response trigger sent via Task Events. That way, the conditional writePort code does not have to be sent in real time, but can be assigned to the generic, real time Task Event marker during this post-processing step. This doesn't help me much for paradigms we've already used, because I've already written a lot of  "Do While xxxxxxxxxx.Mask.IsPending" scripts for sending real-time response codes in those situations. But it will be a LOT easier for me to explain this method, and its simpler writePort command, to graduate students just learning E-Prime, than those complicated "process pending" inline scripts that they borrow and use (and can potentially misuse) without ever understanding.

Sorry if this is too much off-topic. After I've completed my first Task Event ERP study using this method, perhaps I'll start a new Task Event ERP thread with a more optimistic reevaluation.

--------clip---------

[neuro2]

Dear Scott and David,

I was just reading your complaints about lack of  conditional response codes in task events. I wanted to let you know that
we're using a program called Paradigm in our ERP lab that does in fact have this feature (you can specify unique codes for correct, incorrect
and no response). Take a look at their Paradigm Elements for Ports, which is what we're using to interface Paradigm with our Neuroscan:

http://www.paradigmexperiments.com/Elements/Ports/Paradigm-Elements-for-Ports.html

Just a thought.