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

How E-Prime thinks about how you should build experiments

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

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/

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[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.

https://support.pstnet.com/hc/en-us/articles/360009483794-BUG-FIX-E-Prime-hangs-on-the-first-screen-of-an-experiment-run-27780-

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.

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)

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