E-Prime notes: Difference between revisions
mNo edit summary |
|||
(24 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
{{#addbodyclass:tag_tech}} | |||
{{experiments}} | {{experiments}} | ||
Line 243: | Line 244: | ||
:: e.g. to have "start up EEG device" be something only a lab technician has to make, and experimenters need only ''use'' | :: e.g. to have "start up EEG device" be something only a lab technician has to make, and experimenters need only ''use'' | ||
: the packages they call into (.epk3) need to be registered with the experiment, so you still need to set ''that'' up | : the packages they call into (.epk3) need to be registered with the experiment, so you still need to set ''that'' up | ||
====Lists and Procedures (for experiment phases, trials, timelines)==== | ====Lists and Procedures (for experiment phases, trials, timelines)==== | ||
<!-- | |||
It helps to grasp how E-prime thinks about Procedures and Lists, because they determine the flow of the entire experiment. | |||
''Procedures'' | |||
* are a sequence of events | |||
: that are ''usually'' made to correspond to a single trial done in a single way | |||
: so usually consist of at least simple sequence like 'present fixation, present stimulus, record response' | |||
: even if more complex, it is a good idea to keep it in a single sequence | |||
* one procedure will also create a single row in the eventual data file | |||
Because you probably want some variation in which procedures should be run, and some control over that, | |||
Lists aren't just data but also the things that control what procedures get run. | |||
Line 316: | Line 325: | ||
...yes, | ...yes, a List is more of a table than a list. | ||
In this table, | In this table, | ||
Line 405: | Line 413: | ||
--> | --> | ||
====Scripting==== | |||
<!-- | |||
It is suggested that whenever you have the choice to do something in an E-Prime object or in InLine scripting, | |||
to do it via the E-Prime object, | |||
Not because scripting is bad. It is more flexible, but for exactly the same reason it is so much easier to get yourself into trouble. | |||
But the fact that E-Prime objects cannot be altered much, or only in specific ways, | |||
means that is is easier to know what the expected behaviour is. | |||
You start programming, and every quirk of behaviour is on you. | |||
You can absolutely process keypresses yourself, but may not want to if you do not understand what terms like 'concurrent event loops' mean. | |||
Maybe some copy-pasting gets you exactly what you want -- and maybe it means it is broken in ways that only the nearest nearest programmer will understand. | |||
E- | Which is why, if the E-Prime object can be wrangled to do it, that's probably better. | ||
--> | |||
====Reactions==== | |||
<!-- | |||
'''Basics''' | |||
E-Prime is primarily set up to measure | |||
: the interval between | |||
:: an object onset (when something started showing/playing) and | |||
:: a condition being met | |||
That condition | |||
* is ''usually'' "you started pressing a key" | |||
* can also be did you click the mouse (on a specific area of the screen) [https://support.pstnet.com/hc/en-us/articles/115001800567] | |||
--> | |||
<!-- | |||
'''Optionally''' | |||
Independently, it has some built-in logic that lets it | |||
* react only to specific 'correct' responses | |||
* ''count'' those correct-versus-incorrect responses. | |||
: This is only relevant if you care to ''show'' that score to participants during the experiment, which is rarely necessary. | |||
--> | |||
<!-- | |||
'''More creative ''' | |||
An InLine script can also | |||
* ask for any other single value to be recorded in the data file (basically, SetAttribute) | |||
: and do that repeatedly (not always the best way of doing what you want, mind) | |||
* interact with input objects, abusing it any other way you like (as long as you can interrogate the specific interactions), e.g. | |||
** "total amount you held down a key" | |||
** track mouse coordinates [https://support.pstnet.com/hc/en-us/articles/115001909088] -- but note that this is often means "we'll be recording the latest coordinates before we moved on" | |||
** do things like draw on screen live, then save the screen as a file before moving on [https://support.pstnet.com/hc/en-us/articles/1500004775682-Draw-with-mouse-or-finger-37346] | |||
--> | |||
===Some practical aspects to experiment design=== | |||
====Stimuli and responses==== | |||
<!-- | |||
Keyboards themselves report both when you press a key down, and when you release it. | |||
* | E-prime by default only records the key-down, because | ||
* most uses don't require seeing both | |||
* key-down is the earlier event of the two | |||
...but you can change that via Keyboard properties → Keyboard tab → Collection mode. | |||
Chronos, SRBox, Mouse and possible others can also be configured to register both. | |||
Note that if you do, you also need to alter the correct/accepted field for each, because now you probably now need to accept ''both'' (or they'll still be ignores). See the [https://support.pstnet.com/hc/en-us/articles/360049191374 Key naming scheme]. | |||
Note that any object that accepts {ANY} will still exclude release events - for that you will want {ANY}{-ANY} | |||
: this is usually quite sane, in that the moment you switch your keyboard input from "Presses" to "Pressed and releases" you would have to check ''every'' keyboard interaction | |||
:: because "hey what if key-down moved to the next object and releasing it was the input to that next object" would more often be a bug than what you actually intended | |||
When all you want to do with a response is record it and move to the next stimulus (input based and/or timeout), | |||
it is usually simplest to use the object that presents stimuli to record the response. | |||
{{comment|(In the simple demos, and some simpler experiments, that would be a TextDisplay object, in more complex presentation that might be a Slide with multiple things on it)}}. | |||
In simpler cases this is all handled in the '''Duration/Input tab'''. Sometimes you may want some extra handling via Task Events | |||
If you want more complex logic to your responses, | |||
I've seen people put an InLine script directly after the stimulus object, but this can be severe trickery. | |||
The example I'm using at presents a stimulus, ''immediately'' moves on, and counts on the InLine to hold up | |||
...and I'm looking at that because it sometimes freezes. | |||
Duration/Input tab, roughly in order from most to least touched: | |||
* Device(s) | |||
:: you can add any input Device that was added to the experiment | |||
* Allowable - the name of reponses to react to at all | |||
[https://support.pstnet.com/hc/en-us/articles/360049191374 Key naming scheme]. | |||
* Correct | |||
: generally picks up a field from the list row | |||
: only really used if you want E-Prime to report statistics while running | |||
Timing Mode - [[#Timing Mode|see below]] | |||
Data Logging | |||
* Advanced | |||
** Max Count - allows recording of multiple responses, even [https://support.pstnet.com/hc/en-us/articles/115001812847 string input] | |||
** Termination Response seems intended to help with the last, e.g. letting you use {ENTER} to end such input | |||
** Flush Input Buffer - if someone mashed, it will forget all but the first key | |||
OnsetTime | |||
: when the stimulus presentation began | |||
: milliseconds since experiment start | |||
OnsetDelay | |||
: difference between planned onset and actual onset | |||
: in milliseconds | |||
DurationError | |||
: difference between planned duration and actual duration | |||
: in milliseconds | |||
OnsetToOnset | |||
: difference between two object's OnsetTimes | |||
: in milliseconds | |||
--> | |||
====Naming objects==== | |||
Try to rename new objects to something descriptive. | |||
Future you, | |||
the person who processes the data (often you), | |||
other people, | |||
and your lab assistants who are your helpdesk will thank you, | |||
and it usually makes any scripting clearer and easier to debug as well. | |||
If you do or ''will'' do any scripting, do this earlier rather than later, | |||
because changing it later will invalidate existing references in scripts (). | |||
{{comment|(Other E-objects ''should'' be fine because they follow renames, but don't blindly assume that)}} | |||
====Drawing, and display size==== | |||
* There is a "Match Desktop Resolution at Runtime" (in the Display device settings) | |||
: which that tends to look crisp on monitors no matter if their native resolution is different from the one you designed on | |||
* E-prime seems to ''default'' to 1024x768 fullscreen, | |||
: It will look a little low-resolution (and some things may look rescaled/blurry) | |||
:: because while that resolution should be supported by roughly everything, | |||
:: it's also lower than most monitors have been for two decades. | |||
: this is presumably done because drawing positions will be consistent without thinking about the next point | |||
* PST recommend using percentage positions rather than pixels, as this will display more similarly regardless of what monitor resolution you run it on, | |||
: rather than | |||
:: seem to shift to the top left when run on higher resolutions than where you designed it | |||
:: or, more rarely, seem to go off-screen to the right when run on lower resolutions | |||
( | It will ''not'' save you if you decided to e.g. extend your desktop onto another monitor | ||
: (because to windows, this is indistinguisable from a 3840x1080 monitor) | |||
====Thinking about what to log==== | |||
By default, E-prime already logs more than you typically care about, | |||
and it is willing to log a lot more. | |||
It duplicates everything that ''might possibly change'' with any event, so it seems to ''start'' at fifty columns or so, and you rarely care about more than about five once you're done. | |||
This is a little spammy. | |||
That said, the flat structure is easy to process with simpler tools | |||
: it's a decent solution once you do start altering things during a run via scripting | |||
: space is very cheap these days | |||
====Other hints==== | |||
https://pstnet.com/9-common-mistakes-in-e-prime3/ | |||
===More technical=== | |||
<!-- | |||
A lot of experiments can be done with procedures and lists handling the interactions, | |||
and when this fits, this may probe to be relatively little work. | |||
You do have a fairly full programming language at your disposal, though, | |||
so can make things as complex as you want. | |||
However, keep in mind that generating stimuli as you go might cause slow drawing | |||
that limit timing accuracy. In general, try to prepare stimuli beforehand. | |||
--> | |||
=====Task Events===== | |||
<!-- | |||
A set of rules of 'if this event happens, run this task' | |||
(It also groups tasks things into some categories, where E-Basic has ~240 separate methods) | |||
Events include | |||
buttons, | |||
other hardware input | |||
incorrect response, | |||
... | |||
Generally, procedures keep things very controlled, | |||
so the most structural reason to use this may be to integrate with external hardware? | |||
* [https://support.pstnet.com/hc/en-us/articles/115015199548 E-STUDIO: Using Task Events] | |||
* [https://support.pstnet.com/hc/en-us/articles/115015040608 E-STUDIO: Configuring Task Events] | |||
--> | |||
====InputMasks==== | |||
<!-- | |||
An InputMask seems to represent a specific input device, masked by things like what input is considered at all, and for how long to listen to it {{verify}} | |||
Each Object may have one or more InputMasks - normally configured via the duration/Input tab, and via [https://pstnet.com/ecr/E-Objects/RteRunnableInputObject.InputMasks-Property.htm RteRunnableInputObject.InputMasks] if you're. | |||
Scripting can also read multiple ''.Responses'' from the object's InputMasks, if you need to do distinct things per presentation. | |||
https://support.pstnet.com/hc/en-us/articles/229366267-E-BASIC-The-Terminate-and-Timeout-methods-for-InputMask-and-InputMaskManager-17219- | |||
Time Limit | |||
* {{inlinecode|(same as duration)}} - often means | |||
:: except when you do Inline-after-object trickery | |||
* {{inlinecode|(end of proc)}} the Procedure terminates the Input Mask when it completes. | |||
* {{inlinecode|(until feedback)}} - refers to a FeedbackDisplay, not a user reaction, so if you do not have one it will actually act like (infinite) | |||
* {{inlinecode|(infinite)}} | |||
:: (can you still stop it via code?) | |||
* number (milliseconds) | |||
An [https://pstnet.com/ecr/E-Objects/RteRunnableInputObject-Object.htm RteRunnableInputObject] will have | |||
* you | * {{inlinecode|.InputMasks}} - an InputMaskManager object that lets you control what to listen for. You typically do this via the UI. | ||
* {{inlinecode|.PendingInputMasks}} - | |||
Dim theResponseObject As RteRunnableInputObject | |||
Set theResponseObject = CRteRunnableInputObject(Rte.GetObject("PresentStimulus")) | |||
theResponseObject.InputMasks.Responses | |||
theResponseObject.InputMasks.Responses.Count | |||
Procedure.ProcessPendingInputMasks | |||
https://support.pstnet.com/hc/en-us/articles/115011298368 | |||
https://support.pstnet.com/hc/en-us/articles/360020940774-INFO-Procedure-ProcessPendingInputMasks-19271- | |||
https://support.pstnet.com/hc/en-us/articles/229354507-INFO-InputMask-items-appear-gray-to-indicate-the-state-17235- | |||
--> | |||
====Scripting==== | |||
<!-- | |||
General advice: avoid scripting until you use it. | |||
There are some things you can only do with scripting. | |||
There are also ''problems'' unique to scripting. | |||
Scripting object [https://support.pstnet.com/hc/en-us/articles/360011218993] | |||
* you can draw on the canvas via scripting (...not directly) | |||
* Summation Object | |||
: "Summation objects are used to collect a series of observations. From this collection, various summary measures may be determined, such as the minimum or maximum value in the collection, the number of observations, and various statistical measures, such as the mean, standard deviation, or variance of the observations within the collection. For example, in order to determine overall accuracy in a block of trials, a Summation object may be used to keep track of the individual observations, and to calculate the desired measure from the total collection." | |||
* Debug Object | |||
: The Debug object encapsulates a set of useful debugging mechanisms. The Debug.Print command sends a string to the Debug tab in the Output window at run-time, which is helpful when verifying sampling sequences or timing presentation of an object. The Debug commands may be used when developing or testing a new program. See article SCRIPTING: Steps for Writing E-Prime Script [22880] for further debugging information | |||
'''"What is c.SetAttrib"?''' | |||
There is the concept of a Context object, objects that particularly scripting can refer to, mostly for logging data. | |||
There appears to be | |||
* a global Context | |||
* an object-specific context c {{verify}} | |||
:: if you SetAttr, it will turn up logged for that list item in the .edat file | |||
If you want scripting to report multiple things about | |||
...and since you can also GetAttrib, you can also use it for | |||
state you want react to, alter stimuli presentation during the experiment | |||
See also: | |||
* https://pstnet.com/ecr/E-Objects/Context.SetAttrib-Method.htm | |||
* https://pstnet.com/ecr/E-Objects/Context-Object.htm | |||
'''"User script"''' under experiment mainly for globals | |||
'''InLine''' objects [https://support.pstnet.com/hc/en-us/articles/115011962348] | |||
: for more precise control | |||
'''"Full script"''' is the generated everything, and read-only. | |||
'''PackageCall Object''' [https://support.pstnet.com/hc/en-us/articles/115011986608] | |||
: to share code between experiments | |||
: created with [https://support.pstnet.com/hc/en-us/articles/115000902588 PackageFile Editor] | |||
--> | |||
====Debugging==== | |||
<!-- | |||
< | |||
https://support.pstnet.com/hc/en-us/articles/115000902728-SCRIPTING-Debugging-22913- | |||
https://support.pstnet.com/hc/en-us/articles/ | |||
--> | --> | ||
===Exiting early=== | |||
'''''By the experimenter''''' | |||
{{ | {{keyhold|Ctrl}}{{keyhold|Alt}}{{key|Backspace}} | ||
: seems to stop after currently running object{{verify}} | |||
: ''will'' produce an {{inlinecode|.edat}} file - that is almost certainly incomplete, but that's to be expected | |||
: because of the flexibility of this environment, 'after the current object' might sometimes have side effects, sometimes even including some that prevent exit{{verify}} | |||
: https://support.pstnet.com/hc/en-us/articles/360019591114 | |||
{{keyhold|Ctrl}}{{keyhold|Alt}}{{key|Shift}} | |||
: stop ''now'' - treat this as an emergency, | |||
: useful while debugging but not when doing actual experiments, because... | |||
: Will '''not''' generate a {{inlinecode|.edat}} file | |||
: https://support.pstnet.com/hc/en-us/articles/115000902848 | |||
The data seems to be written to disk as an experiment goes on (in a .txt file), | |||
so even when an edat file is not generated (clean exit, usually happens at the very end), | |||
you can use the E-Recovery program to read that written-as-it-went .txt file, and generate a .edat file (that will be incomplete because you stopped the experiment) -- but this is considered an emergency provision, and you should not count on this in regular use. | |||
{{comment|(Note that if an experiment is frozen, these two or others will not work)}} | |||
'''''By the experiment''''' | |||
You can | You can have your code do a call to {{inlinecode|Terminate()}} on the current list, which means "skip the rest of this specific list" (and thereby all Procs it implies). | ||
This may be the most controlled way to for you to | |||
: know and/or control exactly what is being skipped | |||
: and to have some end-of-experiment cleanup still happen. | |||
...but you'ld first need a clear reason to do so. | |||
You could do that in an otherwise regular keyboard response by adding a special key that does that. | |||
For example, in the standard NestedList example, you might add an Inline at the end of TrialProc that does: | |||
<syntaxhighlight lang="vb"> | |||
if StrComp(Stimulus.RESP, "T", 1) = 0 Then | |||
TrialList.Terminate | |||
BlockList.Terminate | |||
End If | |||
</syntaxhighlight> | |||
...a little awkward in that you would also need to include T (or whatever it is) into all your allowed responses, and consider what that actual value is - here we used a capital T so that people would probably need to hit Shift-t, which is less likely to happen accidentally. | |||
...and that last detail can be avoided with the following: | |||
E-Prime will listen to the {{keyhold|Ctrl}}{{key|Shift}} combination and will set internal state so that {{inlinecode|GetUserBreakState()}} returns true. | |||
It does nothing else - you still need to check GetUserBreakState yourself ''and'' do your own informed "this is how to most gracefully stop this specific experiment" ''based'' on that. In the same example that might be: | |||
<syntaxhighlight lang="vb"> | |||
If GetUserBreakState() Then | |||
TrialList.Terminate | |||
BlockList.Terminate | |||
End If | |||
</syntaxhighlight> | |||
There is also a {{inlinecode|SetUserBreakState()}}, which would lead to the same clean exist, though you generally wouldn't need to unless you have both the Ctrl-Shift and some additional code-level reasons to exit the same way. | |||
https://support.pstnet.com/hc/en-us/articles/115002035608 | |||
<!-- | |||
Note that in experiments with multiple phases, there are probably according lists, so similar logic can be used to move on to the next phase of an experiment. You may want to avoid this breakstate stuff so that that is done ''only'' based on the conditions you care about. | |||
{{comment|(If you wanted "move on to the next section of the experiment after 10 minutes, regardless of how many answers you got done exactly" (or various other reasons), you might want to ''avoid'' this breakstate stuff)}} | |||
--> | |||
<!-- | |||
Or, if you like to debug this, | |||
If GetUserBreakState() Then | |||
c.SetAttrib "UserBreak", "Yes" | |||
Else | |||
c.SetAttrib "UserBreak", "No" | |||
End If | |||
--> | |||
===When things go wrong=== | |||
====Freezes==== | |||
{{stub}} | |||
''' | '''What to do when freezes make interaction impossible''' | ||
While {{keyhold|Ctrl}}{{keyhold|Alt}}{{keyhold|shift}} asks E-prime to immediately stop, but if the process itself has become entirely unresponsive (hanging, frozen, whatever you want to call it) for any reason, it seems your only resort is to end the process. | |||
Probably using [[Task Manager]]. | |||
E-prime wants to run fullscreen (and seems to have always-on-top behaviour as well), so... | |||
: if using a single monitor, even if you can switch to another program (like task manager), you won't see it. | |||
: on multiple-monitor setups, | |||
:: alt-Tab should get you a cursor back to do things on the other desktop, and/or | |||
:: and {{keyhold|Ctrl}}{{keyhold|Shift}}{{key|Esc}} gives you a task manager {{comment|(Ctrl-Alt-Del and then choosing Task Manager amounts to the same)}} | |||
::: If that seems to do nothing it's probably on the same monitor as E-prime being drawn under it. Press {{keyhold|⊞ Win}} and arrow keys, this should move it between monitors. (if you pressed other things inbetween, press Ctrl-Shift-Esc again before the win-arrow thing) | |||
You can run it in [https://support.pstnet.com/hc/en-us/articles/360011287174 windowed mode] rather than fullscreen which is less controlling -- but PST seems to consider this a debug thing only because it also gives less control of timing?{{verify}} and even gets things wrong? | |||
'''running from the network / loading resources from the network''' | |||
At universities it is not unusual for your profile to be on the network. | |||
And loading files over the network will often take longer than local disk. At best, this makes timing more precarious (E-Prime does do certain pre-loading, but it's not exactly guaranteed). | |||
You generally want to run things from local disk {{comment|(local SSD is preferable over local platter disk)}}, | |||
if only to avoid these potential delays. | |||
While this should rarely cause freezes, they have been observed. | |||
Display busy? | |||
https://support.pstnet.com/hc/en-us/articles/360055529993-BUG-FIX-Freezing-may-occur-on-E-Prime-Go-runs-using-Windows-10-1903-or-1909-36052- | |||
'''antivirus/antimalware scanner''' | |||
A scanner will generally delay IO a little. | |||
On network profiles and/or initial logins, whatever loading happens within the first few minutes may occupy the disk and/or a CPU core for the first minutes. If you have the time before a participant, you might consider waiting for that to calm down (Task Manager's graphs dip to near-zero). | |||
''' | '''Older experiments, newer changes''' | ||
For example, if using E-Prime 3, apparently using the outdated MsgBox(statement) instead of the newer DisplayDevice.MsgBox(statement) can cause this[https://researchwiki.solo.universiteitleiden.nl/xwiki/wiki/researchwiki.solo.universiteitleiden.nl/view/Software/E-Prime/#HUsingTwoScreens][https://support.pstnet.com/hc/en-us/articles/360008221873 ] | |||
There are other interactions you may be using, implicitly or not, that may block. | |||
Say, you are synchornize timing via SNTP (E-Prime can do this itself, see Experiment properties → Timing tab [https://support.pstnet.com/hc/en-us/articles/360008105174-TIMING-E-Prime-SNTP-Realtime-Clock-19471-]). I don't know what happens when that server doesn't seem to like the frequent connections, and aside from a warning in a config file, it doesn't seem all that documented. | |||
--> | |||
====Hardware unresponsive after freezes==== | |||
''Possibly'' some subsystem or hardware got into a weird state, but windows is pretty good about that these days, | |||
so there often is some leftover process. | |||
You could try to stop that with with task manager. | |||
Logging out and back in may be simpler to do though might take a little longer. | |||
The other simple-but-takes longer is to shut down and restart the computer. | |||
Most times this will still be faster than diagnosing. | |||
https://support.pstnet.com/hc/en-us/articles/360009483794-BUG-FIX-E-Prime-hangs-on-the-first-screen-of-an-experiment-run-27780- | |||
====Graphics glitches under load==== | |||
===When timing matters=== | |||
{{stub}} | |||
<!-- | |||
When you ask people whether they want millisecond timing, they will say yes, more precision is more better. | |||
That said, there are a lot of things that aren't precise to that to start with. | |||
Say you play a sound file and measure a response to that. | |||
...if there are a few milliseconds at the start of that file, all responses will be late by that amount of silence. | |||
And that is, generally, not a problem. | |||
In particular if you ''compare'' reaction times, it doesn't really matter if precisely 5 milliseconds are added to ''all'' figure - the difference will be just as pronounced and precise (just a little less accurate to a true value). | |||
''' | If you ''do'' want millisecond accuracy, you must reconsidere ''everything'' you do. | ||
--> | |||
=====Thinking about timing in experiment design===== | |||
<!-- | |||
'''Do you care if the person ''or'' the machine happens to take a little longer ''between'' individual tasks?''' | |||
'''Do you care that that might add up, add a little to the total time taken?''' | |||
If the answer to both is no, your life stays relatively simple. | |||
Reasons you might not care: | |||
* each task is self-contained - e.g. you have a series of questions where you time the answer, but time taken ''between'' the question-answer pairs doesn't matter. | |||
Reasons you might care | |||
* your 20 minute experiment might each take a few minutes longer, and that messes with your participant schedule for the day | |||
Alleviation | |||
* Schedule each of your participants with some time to spare. You probably want that anyway. | |||
''' | '''Do you care if the machine happens to be late presenting a stimulus?''' | ||
Say, if you told it to display an image ''now'', or play a sound ''now'', and it actually takes 30ms for it to fetch and decode it to start presenting it. | |||
Video is a known culprit, and can take longer than that. | |||
Reasons you may care | |||
* If our response timing is relative to when we ''wanted'' it to be there, not when it actually is, then your response time by an unknown, variable amount | |||
* | Reasons you may not coare | ||
* video is usually about giving someone complex information to parse, not precise timing of events within that video | |||
Alleviation: | |||
* PreRelease goes a long way for images and sound | |||
:: less so for video{{verify}} but as mentioned | |||
:: see also [https://support.pstnet.com/hc/en-us/articles/229355007-TIMING-Using-PreRelease-to-Maintain-Millisecond-Timing-17760- TIMING: Using PreRelease to Maintain Millisecond Timing [17760] ] | |||
'''Do you care if the machine happens to present the stimulus a little shorter or longer?''' | |||
See the section about monitors, but roughly speaking, on a typical 60Hz monitor, you can only change what appears on screen every 16ms. | |||
When timing is aware of the monitor, and knows exactly when next image flip appears, | |||
then it can plan that start time exactly, and time from then precisely. | |||
The time of future image flips are still set in stone, though. | |||
{{comment|(native apps can do this to decent accuracy. Browser experiments... less so. TODO: tests) (does DirectX actually tell you, or are we basing this on something like timing of blocking buffer flip calls and assumption of no drift?)}} | |||
Reasons you might not care: | |||
* it's a presentation while also accepting a response (e.g. stroop task) | |||
: | : as long as you know when the start of presentation was, timing relative to it is easy | ||
: (timeout is there only to deal with non-response) | |||
Reasons you might care: | |||
* Your protocol tells you you must present stimulus for e.g. 1000ms, to the millisecond | |||
: a lot of numbers we consider round happen to divide well in 60Hz (1000ms is 60 frames, 800ms is 48, 750ms is 45), but some other numbers will not, and will be show for a handful of milliseconds longer | |||
Alleviations: | |||
* For visuals, [[#On_RefreshAlignment|RefreshAlignment]] helps the ''average'' time be your target (even if for individuals it's still longer or shorter) | |||
'''Do you care if the machine happens to take a little longer ''between'' stimuli belonging to the same presentation?''' | |||
'''Do you care that that might add up?''' | |||
Say you are shown four stimuli in sequence, one second each, and then have a single timed answer (e.g. a memory task), and for some reason or other (e.g. loading on the fly), the presentation took 4.2 seconds total. | |||
Reasons you might not care | |||
* if it's a memory task, chances are this does not invalidate anything. | |||
Reasons you might care | |||
* If you have external devices that you cannot control precisely, e.g. an MRI you can only tell it "4 seconds after presentation start, measure for one second", then the same situation will cut off data collection. | |||
'''Do you have a separate device that you cannot control to very precise timing''' | |||
Separate devices have unique problems, and unique solutions. | |||
For example, in EEG experiments you have a fairly fast signal recorder anyway, so it's not unusual to feed extra markers in time, "I did a thing exactly now", to the EEG recorder (largely because that puts all information and timing in one place, meaning you don't have to join those later, so makes your analysis a lot easier). | |||
---- | |||
''' | '''Most of the above are not ''necessarily'' a problem''' | ||
As already pointed, out, '''if''' delays do not change how well we can pinpoint the start of anything, | |||
then this does not affect precision, | |||
only how long the overall experiment takes. | |||
A little more specifically: Even if the start of a stimulus is later than you thought, | |||
: timing from the start of that stimulus presentations is usually still well defined | |||
: and for the same reason the length of a stimulus on screen is still well defined and typically very controllable | |||
'''When you need to start thinking harder''' | |||
A number of issues can be addressed afterwards (particular where it turns out E-prime logged the start of presentation), but in some cases it's much better to avoiding them in first place. | |||
The "doesn't affect precision" may not be true | |||
* | * for video ''if'' it is presented more latency | ||
:: that said, a lot of tasks with video are 'watch a video, report what you saw' - the watching is not timed, the response may be | |||
* for audio if it is presented with more latency | |||
: this is actually an unnecessarily complex topic | |||
* | * if the mode is set to | ||
--> | |||
====Diving deeper==== | |||
=====On PreRelease===== | |||
<!-- | |||
'''Doing everything seprately''' | |||
Stimuli presentation can be entirely sequential. Do one, get done, start the next. | |||
Any preparation required for presentation would ''have'' to happen when the object starts to be shown - meaning the ''actual'' time it is seen/heard is late by however long that preparation still took. | |||
Because preparation would have to happen ''between'' presentations. | |||
: upsides: | |||
a | :: the stimulus presentation can never accidentally get interrupted by work | ||
: limitations: | |||
:: preparation takes time, so putting it between presentations makes the experiment a 'little'' longer (by the accumulated preparation time, which shouldn't be much more than 30ms per stimulus) | |||
:: a sequence of stimuli that follows a longer-term schedule won't be as regular as you may sometimes want (but this is somewhat rare) | |||
Line 1,108: | Line 1,147: | ||
'''Can we get those down near 0ms (also making presentation schedule to be strictly regular)?''' | |||
Yes, with some footnotes. | |||
First, to do this, E-Prime separates the acts of | |||
* "get the stimulus ready" (e.g. load from disk, decode) | |||
* "present the simulus" | |||
for context, most stimulus preparation is some busywork at the beginning, and then a second or so of very little to do. | |||
If, once idle, you can prepare the work for the next object, then that busywork is done | |||
after the work for the current object, and before the next object needs it. | |||
You can also tell it to preparation during the previous stimulus presentation ('''PreRelease''') | |||
: upsides | |||
:: timing of a sequence can be done on a more regular schedule | |||
: downsides | |||
:: might affect the last bit of the previous stimulus presentation{{verify}} | |||
:: still not guaranteed, just usually okay | |||
''' | '''How much does this really matter?''' | ||
' | In terms of time spent: | ||
: text should be negligible | |||
: loading images should often be no more than up to 30ms{{verify}} (reading stuff from disk, decoding it) | |||
: loading sound should be assumed to take up to 30ms{{verify}} (reading stuff from disk, decoding it) | |||
: loading video is... a bit of a wildcard. | |||
:: just don't expect accurate timing around video. | |||
In terms of your experiment, no prerelease | |||
''Will'' affect | |||
* it often does the length of the overall experiment | |||
:: because it keeps on adding a few dozen milliseconds | |||
''' | Often ''won't'' affect | ||
* length of individual stimulus presentation | |||
* response times of stimuli | |||
:: in that because that is relative to when it ''did'' get presented. | |||
Lack of prerelease It only causes issues when | |||
* multiple stimuli could not be synchronized{{verify}} | |||
* you have external hardware on a timer that you ''cannot'' adapt later. Think MRI machine or such. | |||
' | (this doesn't matter in a lot of experiments, but can) | ||
'''what it means, a little more technically''' | |||
The PreRelease of an object is the amount of time (in ms) that E-Prime will take during the execution of that object, to setup/preload the ''next'' object. | |||
'''PreRelease''' is a property of objects | |||
: actually the maximum number of milliseconds to spend on a next presentation) | |||
:: defaults to (same as duration) since E-Prime 2?{{verify}} | |||
:: (making it shorter than refresh rate is unlikely to help much. A few dozen ms may be enough for most cases, though, and setting it to more ''usually'' has no more effect) | |||
:: When an object just needs to load, this is fine. When an object has a dynamic nature (e.g. InLine) | |||
'''Setting PreLoad to '(same as duration)' ''' {{comment|(introduced in, and default since, E-Prime 2[https://support.pstnet.com/hc/en-us/articles/360020318414-TIMING-PreRelease-defaults-changed-to-promote-better-timing-accuracy-17936-])}} | |||
...amounts to mean "Hi object, once you're done processing your own thing, start doing the ''setup'' of the next one" | |||
'''Setting PreLoad to 0''' | |||
...is equivalent that "start preparing when the schedule says you should be showing" described above. | |||
'''Setting Preload to a specific number''' | |||
A preload of a specific number is "(that amount) before the end of presentation, start setup of the next" | |||
: For example, if you have a text with 3000ms and 500ms preload, it will start working 2500ms into the text object presentation. | |||
: a very small preload (e.g. <20ms) might not always be enough time for the setup to be done in time | |||
: a large enough preload (e.g. above 500ms, ballpark) may have no additional effect, because most things ''are'' done faster than that | |||
Notes: | |||
* In most cases, (same as duration) means things will be prepared in time | |||
* it seems that for InLine scripts, preload is run time | |||
: that means that if | |||
:: the timing of that InLine matters, it will start too soon | |||
:: the InLine needs to respond to a reaction before, it may be too soon | |||
: ...so you often want the object before such an inline to have PreLoad set to 0 | |||
* something similar goes for FeedBack (for the 'may be before the last response' reasons{{verify}}) | |||
* something similar goes for Package Call (for 'we can't know exactly what it will do at this time' reasons{{verify}}) | |||
* something similar goes for the last object in a procedure (?) | |||
* when timing is critical, think hard about PreRelease | |||
'''Are there downsides?''' | |||
Yup. | |||
''it can silently cause other things to behave incorrectly'' | |||
PreRelease is a clever hack, but a hack all the same. | |||
Ideally, it will only start the Load of objects, which should not lead to its presentation. | |||
However, this distinction is fuzzy for some kinds of objects. | |||
It should not be used when the next thing is | |||
* a Feedback object | |||
* an InLine object | |||
* a Package Call | |||
I have also seen it cause sound recording to fail (but have not diagnosed why). | |||
Maybe also be wary of slides with multiple objects, some of which are recording? | |||
''No guarantees'' | |||
PreRelease only says that preparation will start earlier, it still cannot guarantees the preparation ''will'' have happened already. | |||
Around long audio, it may not manage. | |||
I'm not sure it even ''tries'' with video, because this is a component external to it. | |||
For images and short sounds it's fine most of the time, though, and it ''will' record how much late it was, | |||
but when the onset timing is ''absolutely critical'', more attention to this is is important. | |||
--- | --- | ||
"[...] the median duration is longer than the specified duration time, is most strongly | |||
influenced by the time required for stimulus preparation, [...]" | |||
Keep in mind that even after preparing (in the below diagram: '''Setup'''/'''preparation'''{{verify}}), | |||
a fully prepared stimulus may be on your monitor a little later (in the below diagram: '''Sync'''{{verify}}) | |||
---- | |||
There is also the question of what do do after the planned end of a stimulus, and the planned start of the next. | |||
Remove the thing? Leave it there? | |||
[[File:E-prime timing.png|thumb|500px]] | |||
'''Setup'''/'''preparation''' - the work to be done before something can be drawn/listened to/etc. | |||
Perhaps most importantly, | |||
* E-prime does not do all setup before an experiment starts | |||
:: ...presumably because it couldn't guarantee this can always be done | |||
:: ...and fundamentally can't when things can be interactive{{verify}} | |||
* It does it just before presentation starts | |||
'''Sync''' - | |||
'''TargetOnsetTime''' | |||
'''OnsetDelay''' = OnsetTime - TargetOnsetTime | |||
: i.e. the time between planned/scheduled target onset time, and actual onset time | |||
'''StartTime''' - | |||
'''StopTime''' - | |||
'''OnsetTime''' - milliseconds from the start of the experiment to when onset action begins | |||
: (for visual items, when draw commands happen; for SoundOut, when playback begins, etc.) | |||
'''ActionTime''' - | |||
'''ActionDelay''' = ActionTime - OnsetTime | |||
: (ideally there should be ≤1ms difference?) | |||
'''OffsetTime''' - milliseconds from the start of the experiment to when offset action (e.g. drawing on screen) begins | |||
''' | '''OffsetDelay''' - | ||
''' | '''OffsetDelay''' = OffsetTime - TargetOffsetTime | ||
execution duration? = OffsetTime - OnsetTime | |||
- | '''FinishTime''' - | ||
: generally there should be ≤1ms difference between FinishTime and OffsetTime | |||
'''DurationError''' - OffsetTime + PreRelease - OnsetTime - Duration | |||
: difference between the actual duration and intended duration | |||
'''OnsetToOnset''' - The ''actual'' duration something is on-screen may be OnsetTime to the next thing's OnsetTime | |||
: (because the logged Duration in the log is the ''requested'' duration (as configured)) | |||
: the best metric for how long an object was visible | |||
(note: various of those you'll only see around TimeAudit) | |||
https://researchwiki.solo.universiteitleiden.nl/xwiki/wiki/researchwiki.solo.universiteitleiden.nl/view/Software/E-Prime/ | |||
: | |||
https://andysbrainbook.readthedocs.io/en/latest/E-Prime/E-Prime_ShortCourse/EP_03_Duration_Termination_Pre-Release.html | |||
--> | |||
=====Generate PreRun===== | |||
Generate PreRun (Object's Common tab) controls ''when'' external resources are loaded. | |||
BeforeObjectRun - loads right before execution (see also PreRelease) | |||
TopOfProcedure - loads at the beginning of the procedure, before any of its objects. | |||
E-Prime 2 defaulted to TopOfProcedure | |||
E-Prime 3 defaults to BeforeObjectRun | |||
In an "avoid doing things at the last minute because that may delay things" way, TopOfProcedure is preferable. | |||
In a "that makes it sort of out of order, so if you are doing interesting scripting it may not do what you want" way, | |||
e.g. want to control what it should load in the procedure e.g. via c.SetAttrib, | |||
that won't work ''because'' that load already happened earlier. | |||
It seems E-Prime 3 defaults BeforeObjectRun to avoid this particular confusion, at the cost of onset delays (which usually don't matter) | |||
=====On RefreshAlignment===== | |||
<!-- | |||
Consider that the Duration ''may'' not be an exact multiple of the screen time. | |||
For a round-numbered example, say we actually had a 100Hz monitor, for nicer round numbers of 10ms intervals. | |||
Say we asked for a 202ms Duration. Or a 207ms Duration. | |||
If | If our logic is 'we aim to take it off-screen the next refresh after the target time', the duration will just always be 210 both both examples, | ||
and it would always be on screen longer than requested. By 8 and 3ms, respectively. | |||
If we could aim for closest, it would be always shorter (200) for the 202 example, but would be always longer (210) for e.g. 206. | |||
''' | If we wanted to get that Duration closer ''on average'', then there is some extra trickery. | ||
It's not perfect, but it's better. | |||
Basically, you tell E-Prime to schedule to take it off a frame ''earlier'' some of the time - whenever that's fairly soon. | |||
But also, if we didn't syncr | |||
--- | |||
Assume our own timing isn't perfectly in sync with the monitor frames. | |||
That makes the numbers messier (every now and then it would be much less), but it would still be always positive, and still tend towards ''roughly'' 8ms{{verify}} longer on average. | |||
[[File:Refresh alignment.png|thumb|right|400px]] | |||
Now consider being able to say "if schedulingwise it turns out you have the opportunity to put the next thing on screen 5ms ''earlier'' than planned, that's also fine". Now, scheduling would become a mix of | |||
: < 10 ms late | |||
: ≤ 5 ms early | |||
We still know when we started putting things on screen, that doesn't change. | |||
The average duration is now ''less'' than 8ms. Not zero, but closer to it. | |||
Refresh Alignment can be intuited as how much of an object's Duration time can be sacrificed in order to do that. | |||
Or, from a wider view, it lets you spread the error around objects better, making for better timing on average{{verify}} | |||
As a setting, Refresh Alignment is a percentage - of the refresh rate, so e.g. for 60Hz, 25% means it schedules it a frame early if that is less than (0.25 * 1/60≈) 4.2ms earlier{{verify}}. Defaults to 25% so that's what it actually means for many screens. | |||
Also, consider that ''if'' there are related stimuli for which the timing must be precise, then you may care to do some careful planning. | |||
: the screen is essentially the slowest device so you probably want to time things relative to the frame things start showing, and not e.g. show things relative to when you trigger a sound. | |||
If you only care about the ''length'' of the stimulus on screen, this doesn't matter - it starts whenever it starts and we start counting from there. | |||
An object's 'Onset Sync' defaults to 'vertical blank', basically meaning "wait until the next frame being shown" (will not doing so potentially do screen tearing?). | |||
In theory this means things are on the screen late compared to when you started to care about a stimulus, | |||
but this is not an issue for presentation of visual stimuli, because you can make the start of the frame the start of whatever timer. | |||
The shorter the presentation duration, the more it can matter to make it a multiple of the refresh rate. | |||
'''Onset Sync''' - typically vertical sync | |||
'''Offset Sync''' - typically none, but practically still vertical sync because it will coincide with the onset of the new object | |||
--> | |||
=====Timing Mode (property of an object in a procedure)===== | |||
{{stub}} | |||
[[File:E-prime timing modes.png|thumb|550px]] | |||
'''Event''' - keep on-screen for '''at least''' as long as Duration - timed from the start of ''presentation'' <!-- onset? --> | |||
: If there was delay in preparation, that will not affect the presentation time, which implies it will make the entire experiment take a little longer | |||
'''Cumulative''' - timed from start of ''attempt'' to present, so '''stops no later than initially planned''', regardless of whether the start was delayed | |||
:: this may shorten the presentation, but would help the experiment take exactly as long as planned | |||
'''Custom''' - ? | |||
Practically, | |||
* in terms of response time | |||
:: response time is measure from the start of presentation{{verify}} so "how fast you respond to a thing" measurement is not really affected | |||
:: yes, 'cumulative' can chops off some amount of milliseconds at the end that people could respond in -- but generally your duration is long enough that 'at the last possible milliseconds' should be outliers anyway. | |||
:: It would matter to things that are ''planned'' to be very brief, and little else. | |||
* when you have external devices | |||
: consider you have an fMRI machine that samples for exactly 60 seconds, in which you do 12 5-second questions. | |||
:: Event's delays might mean it turns off in the middle of the last question | |||
:: Cumulative might start presenting each a ''little'' late, but it is a lot simpler to know that that delay, and match response data to fMRI data | |||
* As [[#PreRelease|PreRelease]] is enabled by default, these scheduling issues are ideally uncommon in ''either'' Event and Cumulative | |||
=====Audio playback and recording timing===== | |||
<!-- | |||
See the section below. | |||
If you only need to ''compare'' response time this matters much less, | |||
but if the absolute value matters, and matters to more precision than a dozen milliseconds, this is important. | |||
You control relatively little of this in E-Prime. | |||
Mostly the Sound API - the configuration of Devices → sound | |||
* ASIO | |||
: best choice when you have ASIO hardware (mostly external mic / sound cards) | |||
: ...but only work son devices that specifically support it -- including most external audio interfaces, and excluding most internal sound cards. | |||
: assume no better than 5ms | |||
* CoreAudio | |||
: the best choice for ''generic'' (non-ASIO) sound hardware (arguably better than DirectX) | |||
: assume no better than 10ms | |||
* DirectX | |||
: The remark of "Use of DirectSound for machines running Windows Vista, Window 7 (or later) is not recommended for paradigms that require sound latencies under 30ms."[https://support.pstnet.com/hc/en-us/articles/229363067-AV-Editing-the-SoundDevice-API-for-DirectSound-ASIO-CoreAudio-or-Chronos-18865-] isn't because DirectX got worse, it's because CoreAudio exists since then and can do better, so DirectX became more of a fallback | |||
: assume no better than 30ms (and it might be more) | |||
* Chronos | |||
: the chronos box can prepare by loading, and can in theory start playback within 1ms | |||
: (it's not that generic hardware couldn't be designed to do that, it's that it ''isn't'' because roughly nothing else in the world needs it) | |||
Notes: | |||
* I've had problems with E-Prime creating loud-noise issues (stuck ringbuffer sound), specifically when set to CoreAudio | |||
: presumably this is because of buffer-size reasons, but E-Prime offers no control? (maybe ASIO4All) | |||
: Switch to ASIO when you can, DirectX when you must | |||
--> | |||
====When you have separate devices you do not control precisely==== | |||
====Experiment Advisor Reports==== | |||
<!-- | |||
'''"Duration not divisible by refresh rate"''' | |||
If you set unusual and/or very short durations, chances are something's going to be on screen for half a second shorter or longer - on an 60Hz monitor ''on average'' off by 8ms or so. | |||
: whole seconds are fine | |||
:: on 60Hz, multiples of 0.1s are fine (6 frames) | |||
:: on 75Hz, multiples of 0.2s are fine (15 frames) | |||
For longer stimuli, a handful of extra milliseconds won't make the world of difference. | |||
For very short presentations, you may well care. | |||
'''"The 'Sound' device is using the DirectSound API on Windows Vista or later which typically cannot achieve latency values under 30ms. ..."''' | |||
DirectSound is an older API, that may be a little less likely to cause trouble, but sounds may come out more than 30ms later than planned. | |||
CoreAudio can be expected to push that down 10ms but this varies. | |||
ASIO is surer to push it under 10ms. | |||
a Chronos device, if you have one, can do certain thing to the millisecond{{verify}} | |||
'''"The display adapter of the machine is set to clone or mirror mode."''' | |||
Under such a configuration it is impossible to know/determine when exactly each monitor's refresh rate is. | |||
'''"Procedure ends with pending InputMask"''' | |||
'''"The 'Display' DisplayDevice has the "Match desktop resolution at runtime" property "''' | |||
The further explanation isn't clear to me, but I assume E-Prime has more control over the graphics process in full-screen mode, | |||
and apparently better timing (and performance?) as a result. | |||
https://support.pstnet.com/hc/en-us/articles/360008184434 | |||
'''"Non-Visual object using OnsetSync or OffsetSync"''' | |||
"A non-visual object (SoundOut, SoundIn, Wait) has either of its OnsetSync or OffsetSync properties set to (vertical blank) which is usually unnecessary unless syncing with external equipment." | |||
https://support.pstnet.com/hc/en-us/articles/360019927114 | |||
--> | |||
==Unsorted== | |||
===What is this ebLCase and ebUCase stuff?=== | |||
For example | |||
ebLCase_s | |||
ebUCase_s | |||
are constants for strings s and S | |||
So | |||
Const attrib_weight = ebUCase_W & ebLCase_e & ebLCase_i & ebLCase_g & ebLCase_h & ebLCase_t | |||
is basically the string "Weight" | |||
Why is it done like that? | |||
https://support.pstnet.com/hc/en-us/articles/360019773853-E-BASIC-List-generates-Const-for-all-Attribute-names-17973 | |||
...iono. | |||
https://pstnet.com/ecr/EBM/Constants.htm | |||
https:// | |||
Latest revision as of 12:17, 17 May 2024
Notes related to setting up behavioural experiments and such.
|
E-prime lets you do a good amount of things with just its drag and drop GUI style designer and built-in elements.
You can add scripting (Visual Basic) if you need to (though it is discouraged to have complex code, also for timing reasons).
Given it is paid-for and pricy software, with its own also-pricy hardware (Chronos) if you want better response latency,
you may want to look at alternatives both in software and hardware (but to be fair, Chronos does a few things other hardware may not).
Parts of the overall software
E-Studio - creating an experiment
- You could also do test runs from here, or even real runs
- though you might prefer E-Run
- because can run that on more computers for cheaper
- and for details like that you can't accidentally alter the experiment
E-Run -
- when you want to run an experiment, you can run it from E-studio (it will compile it to an .ebs file(verify)), but...
- E-Run is a simpler environment that only runs an experiment, with fewer moving parts for you to touch and break
- (also the licensing to run (and only run) things on many machines can be cheaper(verify))
- creates a .txt log and, (only) if ended gracefully, an .edat file
E-Recovery [1]
- when an experiment is broken off abrubtly (see #Exiting_early), it has not generated its final data file, but it will have written the ongoing data. E-Recovery converts the latter into a typically-incomplete .edat file
E-Merge - [2]
- Generally, you have one .edat output file for each subject (or session).
- This merges them into one .emrg
E-DataAid - helps deal with the collective output of experiments (so practically often .emrg, though it also opens .edat)
- including some Excel-like analysis
- and writing to file formats readable by something office or statistics software (seems to all be TSV variants(verify))
How E-Prime thinks about how you should build experiments
Devices (presentation and input)
The Experiment object's properties has a Devices tab that lists the devices that objects and code can actively manipulate. (usually added on a need basis, in part because each may introduce some configuration for you to think about)
The defaults include Display, Keyboard, Mouse, Sound, which covers a lot of practical uses.
and don't need to add any until you interact with specific hardware,
and you only sometimes wish to tweak settings.
Button and Script are there for slightly more complex reasons, that you don't need to understand initially.
- Display[3]
- useful settings include e.g. resolution, refresh
- Sound - playback/output only
- lets you configure a sound API (CoreAudio/WASAPI, DirectSound, ASIO, Chronos) but not which sound card (except ASIO?) -- presumably whatever is the default or is current? (in the case of DS/CA controlled by windows?)
- assume DirectSound has 30ms latency (=how late it is with playing back sound); CoreAudio may be around 5..10ms but if you need to be sure, measure it
- SoundCapture
- even fewer settings (than the playback) - just rate and channels
- Presumably follows the Sound config?(verify)
- Keyboard
- note: assume USB keyboards have ~15ms latency
- also, if you would press extremely regularly you would still get variation in recorded timing, because the schedule in which it polls the keyboard is unrelated to what you are doing (and cannot be synchronized)
- Mouse
- note: assume mice might have ~15ms latency(verify)
- Joystick
- note: assume joystick input might have ~15ms latency(verify)
- Chronos
- more precise button presses
- more precise sound playback
- SRBox - Chronos Box's predecessor
- Serial, Parallel (hardware ports)
- you can generally assume serial ports can react under 2ms. Some are better, some are worse.
- Socket (network)
- probably mostly used for remote control
- Script -
- apparently there to give you control of specific timing?(verify)
- always there
Touchscreens and stylus input are not supported. They are supported only in that OSes will typically emulate mice, but assume this is more latency.
Multitouch is not supported, by implication of mice not doing that. [4]
Monitor resolution
Multiple monitors
Objects
Overall structure
Procedure - an ordered timeline of objects to handle [5]
- jumps can change order
- can't jump into other procedures (though you can nest them in timelines?)
List[6] -
- intended to organize (trial) data used within the experiment
- e.g. independent variables (called 'attributes', to avoid confusion with variables as in code) and their levels
- Interactive Lists allows control over order while testing [7]
Wait [8] - amount of time
Label [9] - target of Jump (which other objects and scripting can do)
- Presentation of simple things (in sequence)
'TextDisplay[10]
ImageDisplay[11]
MovieDisplay [12]
- can specify start and end time/frame
Notes:
- For supported formats for audio and movie, see [13]
- video uses ffmpeg so should easily support at least DivX, XVid, MPEG-1, MPEG-2, MPEG-4, H-264, WMV
- Presenting complex things (combined / parallel)
Slide[14] -
- where the above handful stimuli-like things are one-on-a-screen things that help keep simple experiments simple ("show text, ask for response")
- ...Slide seems to largely exists to have lets you present multiple concurrent stimuli, with one collective Input/Duration
SlideState [15]
- where a Slide is a toolbox object you can put in a procedure, a SlideState lets you split one Slide into multiple presentable things - e.g. useful to have one step in a procedure be able to present alternative stimuli
- Any Slide starts with a single SlideState
- One way to use these is to have a slide's ActiveState be based on a list column, e.g. [PresentState]
(SlideState) sub-objects [16] refers to things you can put into a Slide / SlideState
- The kind of things you can put on here overlaps lot of the toolbox one-on-a-screen things (consider SlideText[17], SlideImage[18])
- but also has things that mainly make sense in combination (consider SlideButton[19], SlideChoice[20], SlideSlider[21]),
- and/or that may work a little different in combination (consider SlideSoundOut[22], SlideSoundIn[23], SlideMovie[24])
- Each of these can still have their own Input/Duration but this is generally not advisable in that there are various interactions you could set up that make no sense and will do weird things)
- seem to be meant to structure both stimuli presentation, and thereby also structure of collected data (verify)
FeedbackDisplay [25]
- is mostly just a pre-made Slide with three/four SlideStates (Correct, Incorrect, NoResponse, Pending (?))
- special-cased to present feedback based on the input from another object
- the last response, plus some of its own processing to allow showing statistics from previous reponses
- Other objects that exist
InLine[26] -
- user-written script, run at a point in a Procedure
- compare to
- User Script (run only at startup(verify), and a fixed part of Experiment)
- https://andysbrainbook.readthedocs.io/en/latest/E-Prime/E-Prime_ShortCourse/EP_08_InlineObjects.html
Experiment - fixed, single parent of everything [27]
- General, Notes - record things like author name, version, notes
- Startup Info - what things to ask for and log - defaults to subject and session number, you can add more
- Data File - by default, a log is written per experiment+subject+session
- Devices - which devices this experiment is configured to use -- see #Presentation_output_and_response_input_devices
- Experiment Advisor - helps alert various timing issues
- in design (during generation)
- while running
PackageCall[28]
- meant for code shared by (and constant between) experiments
- you may never use/need these, they may be part of how your lab works
- e.g. to have "start up EEG device" be something only a lab technician has to make, and experimenters need only use
- the packages they call into (.epk3) need to be registered with the experiment, so you still need to set that up
Lists and Procedures (for experiment phases, trials, timelines)
Scripting
Reactions
Some practical aspects to experiment design
Stimuli and responses
Naming objects
Try to rename new objects to something descriptive.
Future you, the person who processes the data (often you), other people, and your lab assistants who are your helpdesk will thank you, and it usually makes any scripting clearer and easier to debug as well.
If you do or will do any scripting, do this earlier rather than later,
because changing it later will invalidate existing references in scripts ().
(Other E-objects should be fine because they follow renames, but don't blindly assume that)
Drawing, and display size
- There is a "Match Desktop Resolution at Runtime" (in the Display device settings)
- which that tends to look crisp on monitors no matter if their native resolution is different from the one you designed on
- E-prime seems to default to 1024x768 fullscreen,
- It will look a little low-resolution (and some things may look rescaled/blurry)
- because while that resolution should be supported by roughly everything,
- it's also lower than most monitors have been for two decades.
- this is presumably done because drawing positions will be consistent without thinking about the next point
- PST recommend using percentage positions rather than pixels, as this will display more similarly regardless of what monitor resolution you run it on,
- rather than
- seem to shift to the top left when run on higher resolutions than where you designed it
- or, more rarely, seem to go off-screen to the right when run on lower resolutions
It will not save you if you decided to e.g. extend your desktop onto another monitor
- (because to windows, this is indistinguisable from a 3840x1080 monitor)
Thinking about what to log
By default, E-prime already logs more than you typically care about, and it is willing to log a lot more.
It duplicates everything that might possibly change with any event, so it seems to start at fifty columns or so, and you rarely care about more than about five once you're done.
This is a little spammy.
That said, the flat structure is easy to process with simpler tools
- it's a decent solution once you do start altering things during a run via scripting
- space is very cheap these days
Other hints
https://pstnet.com/9-common-mistakes-in-e-prime3/
More technical
Task Events
InputMasks
Scripting
Debugging
Exiting early
By the experimenter
CtrlAltBackspace
- seems to stop after currently running object(verify)
- will produce an .edat file - that is almost certainly incomplete, but that's to be expected
- because of the flexibility of this environment, 'after the current object' might sometimes have side effects, sometimes even including some that prevent exit(verify)
- https://support.pstnet.com/hc/en-us/articles/360019591114
CtrlAltShift
- stop now - treat this as an emergency,
- useful while debugging but not when doing actual experiments, because...
- Will not generate a .edat file
- https://support.pstnet.com/hc/en-us/articles/115000902848
The data seems to be written to disk as an experiment goes on (in a .txt file), so even when an edat file is not generated (clean exit, usually happens at the very end), you can use the E-Recovery program to read that written-as-it-went .txt file, and generate a .edat file (that will be incomplete because you stopped the experiment) -- but this is considered an emergency provision, and you should not count on this in regular use.
(Note that if an experiment is frozen, these two or others will not work)
By the experiment
You can have your code do a call to Terminate() on the current list, which means "skip the rest of this specific list" (and thereby all Procs it implies).
This may be the most controlled way to for you to
- know and/or control exactly what is being skipped
- and to have some end-of-experiment cleanup still happen.
...but you'ld first need a clear reason to do so.
You could do that in an otherwise regular keyboard response by adding a special key that does that.
For example, in the standard NestedList example, you might add an Inline at the end of TrialProc that does:
if StrComp(Stimulus.RESP, "T", 1) = 0 Then
TrialList.Terminate
BlockList.Terminate
End If
...a little awkward in that you would also need to include T (or whatever it is) into all your allowed responses, and consider what that actual value is - here we used a capital T so that people would probably need to hit Shift-t, which is less likely to happen accidentally.
...and that last detail can be avoided with the following: E-Prime will listen to the CtrlShift combination and will set internal state so that GetUserBreakState() returns true. It does nothing else - you still need to check GetUserBreakState yourself and do your own informed "this is how to most gracefully stop this specific experiment" based on that. In the same example that might be:
If GetUserBreakState() Then
TrialList.Terminate
BlockList.Terminate
End If
There is also a SetUserBreakState(), which would lead to the same clean exist, though you generally wouldn't need to unless you have both the Ctrl-Shift and some additional code-level reasons to exit the same way.
https://support.pstnet.com/hc/en-us/articles/115002035608
When things go wrong
Freezes
What to do when freezes make interaction impossible
While CtrlAltshift asks E-prime to immediately stop, but if the process itself has become entirely unresponsive (hanging, frozen, whatever you want to call it) for any reason, it seems your only resort is to end the process.
Probably using Task Manager.
E-prime wants to run fullscreen (and seems to have always-on-top behaviour as well), so...
- if using a single monitor, even if you can switch to another program (like task manager), you won't see it.
- on multiple-monitor setups,
- alt-Tab should get you a cursor back to do things on the other desktop, and/or
- and CtrlShiftEsc gives you a task manager (Ctrl-Alt-Del and then choosing Task Manager amounts to the same)
- If that seems to do nothing it's probably on the same monitor as E-prime being drawn under it. Press ⊞ Win and arrow keys, this should move it between monitors. (if you pressed other things inbetween, press Ctrl-Shift-Esc again before the win-arrow thing)
You can run it in windowed mode rather than fullscreen which is less controlling -- but PST seems to consider this a debug thing only because it also gives less control of timing?(verify) and even gets things wrong?
running from the network / loading resources from the network
At universities it is not unusual for your profile to be on the network.
And loading files over the network will often take longer than local disk. At best, this makes timing more precarious (E-Prime does do certain pre-loading, but it's not exactly guaranteed).
You generally want to run things from local disk (local SSD is preferable over local platter disk), if only to avoid these potential delays.
While this should rarely cause freezes, they have been observed.
Display busy?
antivirus/antimalware scanner
A scanner will generally delay IO a little.
On network profiles and/or initial logins, whatever loading happens within the first few minutes may occupy the disk and/or a CPU core for the first minutes. If you have the time before a participant, you might consider waiting for that to calm down (Task Manager's graphs dip to near-zero).
Older experiments, newer changes
For example, if using E-Prime 3, apparently using the outdated MsgBox(statement) instead of the newer DisplayDevice.MsgBox(statement) can cause this[29][30]
There are other interactions you may be using, implicitly or not, that may block.
Say, you are synchornize timing via SNTP (E-Prime can do this itself, see Experiment properties → Timing tab [31]). I don't know what happens when that server doesn't seem to like the frequent connections, and aside from a warning in a config file, it doesn't seem all that documented.
-->
Hardware unresponsive after freezes
Possibly some subsystem or hardware got into a weird state, but windows is pretty good about that these days, so there often is some leftover process. You could try to stop that with with task manager. Logging out and back in may be simpler to do though might take a little longer.
The other simple-but-takes longer is to shut down and restart the computer. Most times this will still be faster than diagnosing.
Graphics glitches under load
When timing matters
Thinking about timing in experiment design
Diving deeper
On PreRelease
Generate PreRun
Generate PreRun (Object's Common tab) controls when external resources are loaded.
BeforeObjectRun - loads right before execution (see also PreRelease)
TopOfProcedure - loads at the beginning of the procedure, before any of its objects.
E-Prime 2 defaulted to TopOfProcedure
E-Prime 3 defaults to BeforeObjectRun
In an "avoid doing things at the last minute because that may delay things" way, TopOfProcedure is preferable.
In a "that makes it sort of out of order, so if you are doing interesting scripting it may not do what you want" way, e.g. want to control what it should load in the procedure e.g. via c.SetAttrib, that won't work because that load already happened earlier. It seems E-Prime 3 defaults BeforeObjectRun to avoid this particular confusion, at the cost of onset delays (which usually don't matter)
On RefreshAlignment
Timing Mode (property of an object in a procedure)
Event - keep on-screen for at least as long as Duration - timed from the start of presentation
- If there was delay in preparation, that will not affect the presentation time, which implies it will make the entire experiment take a little longer
Cumulative - timed from start of attempt to present, so stops no later than initially planned, regardless of whether the start was delayed
- this may shorten the presentation, but would help the experiment take exactly as long as planned
Custom - ?
Practically,
- in terms of response time
- response time is measure from the start of presentation(verify) so "how fast you respond to a thing" measurement is not really affected
- yes, 'cumulative' can chops off some amount of milliseconds at the end that people could respond in -- but generally your duration is long enough that 'at the last possible milliseconds' should be outliers anyway.
- It would matter to things that are planned to be very brief, and little else.
- when you have external devices
- consider you have an fMRI machine that samples for exactly 60 seconds, in which you do 12 5-second questions.
- Event's delays might mean it turns off in the middle of the last question
- Cumulative might start presenting each a little late, but it is a lot simpler to know that that delay, and match response data to fMRI data
- As PreRelease is enabled by default, these scheduling issues are ideally uncommon in either Event and Cumulative
Audio playback and recording timing
When you have separate devices you do not control precisely
Experiment Advisor Reports
Unsorted
What is this ebLCase and ebUCase stuff?
For example
ebLCase_s ebUCase_s
are constants for strings s and S
So
Const attrib_weight = ebUCase_W & ebLCase_e & ebLCase_i & ebLCase_g & ebLCase_h & ebLCase_t
is basically the string "Weight"
Why is it done like that?
...iono.