E-Prime notes

Notes related to setting up behavioural experiments and such. Experiment design Hardware and timing Experiment building - on timing · on online experiments · on counterbalancing E-Prime notes · PsychoPy notes · Experiment builder notes · Gorilla notes · PsychToolbox notes · OpenSesame notes · DMDX notes

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))

Turning your experiment idea into a working experiment (a.k.a. how E-prime thinks)

Parts of the E-Studio interface

https://andysbrainbook.readthedocs.io/en/latest/E-Prime/E-Prime_ShortCourse/EP_01_Introduction.html

The left is the Toolbox of things you could add

The middle is the Experiment explorer, mostly used to showing the overall structure of things you have added

and the properties of the selected item (which you can get in a somewhat more organized popup via the property pages entry, or the property icon in the workspace once opened)

The right is the workspace that lets you edit the currently selected thing in the structure view.

note that these things

(Text and audio - probably enter in that order)

To the more technically inclined:

• it likes hierarchical structure

• you put stimuli detail into Lists

randomization/counterbalancing of stimuli is handled in Lists

• lists call into procedures

how simple you keep that, or how complex you make that, is up to you

• procedures include presentation

• the thing that presents a stimulus also records the response

To the less technically inclined:

• the tutorials and videos are pretty decent, if a little verbose

Devices (presentation and input)

✎ This article/section is a stub — some half-sorted notes, not necessarily checked, not necessarily correct. Feel free to ignore, or tell me about it.

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]

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

Responses to objects

✎ This article/section is a stub — some half-sorted notes, not necessarily checked, not necessarily correct. Feel free to ignore, or tell me about it.

Input Devices, Input Masks, and Echoes

The Input Masks area within an Object's Duration/Input tab defines which devices it will respond to, and how.

"Once enabled, a device maintains its own Response Option settings as a mask on the device. Selection of a device in the Device(s) field will display the options for the mask in the Response Options. "

https://support.pstnet.com/hc/en-us/articles/115011298368

Whatever Object presents the stimulus will also be used to records the response to that stimulus.

For very simple cases this may be a lone TextDisplay, ImageDisplay, etc.

For more complex cases, this may be a Slide containing multiple things

Go to that Object, and find (right-click) Properties -> "Duration/Input"

You will find fields controlling

• what kind of thing to record - what device(s) to accept input from

most commonly response box, keyboard, mouse, but

...but possibly also

joysticks/gamepads (mostly for buttons, x-y is only polled?)

and anything you can manage to connect via hardware ports, or network input

audio recording (though many experiments are desiged to not do this, largely because it's a complex sort of data to deal with afterwards)

Button device [29] lets you look for specific behaviour (like hover, long press, double-click) from Keyboard, Mouse, Joystick (though not Port, response box, etc.(verify))

and in theory can be used to unify responses from multiple types of input (but this is rarely necessary)

• Allowable - what input from that device to consider a valid response at all

lets you ignore accidental input

Because hardware has specifically named buttons you may want to use here, you may care to read valid values for different hardware

• Correct - what the correct response is

yes, you can always score people from their output. This field is primarily useful if you do during-the-experiment scoring that you show to the participant

the value will often (like the stimulus) have to be picked from a list column

• How fast to give up on a user, and move on

which you may want for reaction-time experiments

More timing-related details

A single stimulis presentation may be finised by a timer, and/or by a response before that time.

• If you set a Duration and no input, it will be presented for that long

e.g. useful for fixation

(Duration seems to default to 1sec for new objects)

• When you set input and a Duration, people have only so long to respond

• if you set input and no Duration, the thing will be presented until a (allowable) response

• Time Limit - for how long to accept input

a fixed time may be longer than the procedure we're running or cross into feedback time

(end of proc) may cross into feedback time

(until feedback) will stop if you follow it up with a Feedback object in the Procedure - but if there is none, will act as (infinite)

(infinite)

so generally use (until feedback) if you have feedback, (end of proc) if you don't?

what do multiple responses do?

(Time Limit relation's to Duration?)

---

Sound responses

There is SoundIn[30] (recorded as WAV), but as an individual object it is effectively exclusive with e.g. presentation(verify), so it may well be more convenient to start recording earlier, e.g. using a SlideSoundIn on a Slide (verify)

There is a Voice Key, which is the Chronos responding to any sound on its sound input

that input is not related to whatever SoundIn is recording from

unless you set that to Chronos

and, if you did not set that to chronos, may still be the same if you physically connect the microphone to both your recording device and chronos input

which in theory is a great way to record the start of a response by sound amplitude alone,

...at a configurable amplitude

but in practice will just respond to anything loud enough ('um', tapping foot, whatnot) and you will not know afterwards what that was. So if you care about the timing of a real response, record the audio and use your judgment.

Some practical aspects to experiment design

Introduction and tutorials

• OVERVIEW: Experiment Design Using E-Studio

• E-STUDIO: E-Studio Interface

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

Testing experiments in different ways

Before starting an experiment, test that all buttons, sound input, sound output, etc. works as expected.

''Quick Start helps run parts of your whole experiment in isolation [31]

There are ways in which this differs from running the experiment fully.

Generally few, but it can be worth testing it the slow and full way before moving on to really using it.

E-Run's Test Mode [32] runs through an experiment quickly, automatically giving answers. It is meant to test that it will record what you think it will.

While developing, you may like windowed mode[33] rather than the default full-screen while testing interaction

Going to the final setup

Keep in mind that when you move from design to data collection, you are probably moving from your own PC to a lab PC, which may have a slightly different setup.

It is a good idea to run the entire thing once to check it is doing what you expect.

If you tweak any settings, you probably want to save that copy with a clear indication of "this is a copy that works in the lab" - at least, if you are likely.

Some last minute things to think about:

• it may have distinct sound cards, e.g. for quality recording

run your experiment once to check that it is doing what you expect

particularly if you record audio

• it probably has two monitors

one for you, one for just the subject

PCs are usually set up to consider that the main/first display, so that E-Run will go there by default

• the monitor resolution may differ

not generally an issue - you may prefer a little rescaling over repositioning (verify)

• E-Studio does not seem overly clever at dealing with multiple response boxes

You may need to explicitly tell it which you expect input from

Other hints

✎ This article/section is a stub — some half-sorted notes, not necessarily checked, not necessarily correct. Feel free to ignore, or tell me about it.

https://pstnet.com/9-common-mistakes-in-e-prime3/

"Match desktop resolution"

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

✎ This article/section is a stub — some half-sorted notes, not necessarily checked, not necessarily correct. Feel free to ignore, or tell me about it.

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?

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[34][35]

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 [36]). 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-

Issues and Errors

Multiple sound cards

Presenting on multiple sound cards is not particularly possible to do with accuracy (this is not really PST's fault, though some sort of provisions for this would have been nice).

Device Name: Sound; Unable to play

Seems to mean it can't open a specific sound card.

Could mean it's trying to open the system one in exclusive mode? I don't see a way to ask for a specific device.

There is a 3rd party driver installation issue

Usually actually means "License not found"

Video

E-prime does not preload video. Expect it to not be presented with very precise timing.

This is often fine enough, in that video is often used in a "what did you see" (or how did what you see correlate with what you heard), more than a "when precisely" did you see it. But yeah, it's a bit of a known issue.

Video may stutter. Trying to ensure it's read from local disk, preferably SSD, may lessen that.

Stuttering has been known to cause audio buffer issues. Complain to PST, I suppose?

When timing matters

✎ This article/section is a stub — some half-sorted notes, not necessarily checked, not necessarily correct. Feel free to ignore, or tell me about it.

Diving deeper

Generate PreRun

Generate PreRun (Object's Common tab) controls when external resources are loaded.

Outside of the timing-crucual part, sure, but when exactly?

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)

https://support.pstnet.com/hc/en-us/articles/115000902428-TIMING-Timing-of-E-Objects-22852-

Timing Mode (property of an object in a procedure)

✎ This article/section is a stub — some half-sorted notes, not necessarily checked, not necessarily correct. Feel free to ignore, or tell me about it.

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

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