E-Prime notes: Difference between revisions
m (→E-Prime notes) |
mNo edit summary |
||
Line 6: | Line 6: | ||
E-prime lets you do a good amount of things with just its drag and drop GUI style designer and built-in elements. | 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 | 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. | 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). | |||
Revision as of 15:12, 19 September 2023
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]
- (only) if you stop runs early, you may want to separately convert its (partial) .txt to a (partial) .edat
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)
Experiment properties has a Devices tab that lists the devices that the objects / code can actively manipulate.
As the defaults include Display, Keyboard, Mouse, Sound, a lot of things are covered .
(Button and Script are there for slightly more complex reasons)
and don't need to add any until you interact with specific hardware,
and you only sometimes wish to tweak settings.
- Display[3]
- useful settings include e.g. resolution, refresh
- Sound - playback
- 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 - 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
- SRBox - Chronos Box's predecessor
- Serial, Parallel (hardware ports)
- Socket (network)
- Script - ?
Touchscreens and stylus input are supported only in that OSes will emulate mice, and note that that thy have latency.
Multitouch is not supported, by implication of not mapping to a mouse. [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)
Devices (presentation and input)
Some practical aspects to experiment design
Naming objects
Try to rename new objects to something descriptive.
Future you, other people, and your lab assistanct will thank you, and it usually makes any scripting clearer and easier to debug as well.
Do it early, because changing it later will invalidate existing references in scripts (other E-objects should follow renames, but don't blindly assume that).
Drawing, and display size
PST recommend using percentage positions rather than pixels, as this will display very similarly regardless of what resolution you run it on, rather than seem to shift to the top left
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)
There is a "Match Desktop Resolution at Runtime" (in the Display device settings) and that tends to look crisp on monitors no matter their native resolution.
However, E-prime seems to default to 1024x768 fullscreen, presumably because drawing positions cannot be inconsistent. 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 monitors have been for a decade or two.
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
Scripting
Exiting early
By the experimenter
CtrlAltShift
- stop now - treat this as an emergency
- An .edat file is not generated
- 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, this will not work.
CtrlAltBackspace
- seems to stop after currently running object(verify)
- will produce an edat file - that is probably incomplete
- this 'after the current object' might sometimes have side effects, including some that prevent exit(verify)
- https://support.pstnet.com/hc/en-us/articles/360019591114
By the experiment
You can have code call Terminate a current list, which means "skip the rest of this specific list" (and the Procs it implies), so is probably the cleanest way for you to have oversight of what end-of-experiment cleanup would still happen.
You can e.g. have 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
...though you would have to include it into your allowed response, 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.
It may be easier to use the following: E-Prime will listen to the CtrlShift combination and will set internal state so that GetUserBreakState() returns true. And nothing else. Combined with your own informed "this is how to most gracefully stop this specific experiment" - in this simple example probably:
If GetUserBreakState() Then
TrialList.Terminate
BlockList.Terminate
End If
There is also a SetUserBreakState(), which lets you hook in additional reasons to probably trigger the exact same "stop actual testing".
https://support.pstnet.com/hc/en-us/articles/115002035608
When things go wrong
Freezes
Freezes make interaction impossible
As mentioned above, CtrlAltshift makes E-prime ask whether you want to stop a running experiment.
However, if E-prime is frozen for any reason, it seems your only resort is to use task manager to stop the process.
E-prime seems to run "always on top" and fullscreen,
- so if using a single monitor, even the ability to switch to another program, 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.
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
On RefreshAlignment
Timing Mode (timeline object propery)
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, but will make the session 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