All elements

Element objects are all the stimuli and functionality (e.g. recording response from subject) that can run in trials. For each trial you define in an experiment script, make any number of elements to run in it using <type>Object, e.g. crossObject, keyPressObject, etc. Then input all element objects for the trial to addTrial—this defines the trial. See Building and running an experiment.

There are different element object types, e.g. cross, picture, keyPress, portReceiver, etc. See All documentation or type pb at the MATLAB command line for a list of all types with links to documentation. This page documents properties that all element types have.

We add new element types regularly. If you have requests, contact us.

You can also make your own or receive them from other people—see Getting Started sec 12 and the Element Type Programming Manual (these types won't be on this website but your pb command will include them).

Input properties all elements have

start
end

Default: start = no start cues → element doesn't run
Default: end = no end cues → element must end on its own

Properties start and end set times or cues for the element to start/end at in the trial. Each of these properties is a further struct that can have the following fields. To set a cue, set one of these fields and omit all the others (or leave them = <cd>[]<cd>). You can also set multiple cues, wait times from cues, further customize cues, and more—see below.

.t

Time relative to trial start (sec). 0 = trial start.

.duration (end only)

Time relative to this element start (sec).

.startOf
.endOf

Start/End when another element starts in the trial. Set to a string pointing to an element object by variable name and possibly index you use in the experiment script. Or you can use a string array pointing to multiple elements to listen for when any of them starts. e.g.

<cdsm> "picture"<cdsm>
<cdsm> "pictures(2)"<cdsm>
<cdm>[<cdm><cdsm>"pictures(1)" "pictures(2)"<cdsm><cdm>]<cdm>

Tip: If you have an index in a numeric variable you can use it in an <cdsm>"x"<cdsm> string (but not an <cdsm>'x'<cdsm> string) like this:

<cdsm>"pictures(" <cdsm><cdm>+ n + <cdm><cdsm>")"<cdsm>

For time from element start, add field timeFrom—see below.

endOf is the same except when another element ends.

.response
.responseBy

If you set field response = <cd>true<cd>, the element listens for any response recorded by any response handler element in the trial.

If there are multiple response handlers in the trial, you can use field responseBy instead to listen for any response recorded by a specific response handler. Set to a string/string array, like startOf above.

Note if you want to narrow down what responses or response features (e.g. correct/incorrect) to listen for, you can add field and—see below. For time from response, add field timeFrom.

.trigger
.triggerBy

Like response/responseBy above except listen for a trigger registered by an element in the trial.

Note if you set an element to start/end immediately at a trigger, it will always have some small delay (2 frames average, e.g. ≈ 33 msec at 60 frames/sec) since PsychBench needs time to receive and cue from the trigger. To avoid this, add field timeFrom and set it > 2 frames. (This applies for any event that occurs spontaneously, e.g. also response cues above. See Timing precision for more information.)

You can set also timing for whole trials from a trigger, e.g. in a scanner experiment. See trial object property start.

.preTrial

If you set field preTrial = <cdm>true<cdm>, the element runs in the pre-trial interval. Only simple static visual elements can do this. Also currently you can only run one element in a pre-trial interval. Note to set pre-trial background color, just use trial object property preTrialBackColor.

No start cue occurs – Element doesn’t run

By default a trial ends when no elements are left running or waiting to start at definite times, i.e. time cues like t. Not all elements in a trial need to run—an element will skip if its start cue(s) don’t occur by then.

No end cues needed if element will end on its own

Some elements can end on their own—see the element type documentation for if and when. For example, by default a keyPress element ends on its own when it records one response. If so, you don’t need to set end unless you want the element to end earlier.

Examples

element.start.t = 0
element.end.duration = 2

→ start at trial start and run for 2 sec.

element.start.endOf = <cdsm>"movies(1)"<cdsm>

→ Start when element movies(1) ends. No end cue is set, so the element needs to be able to end on its own.

Adding to a cue: Field and

You can add field and to a response or trigger cue to further customize it. Set and to a string that is any MATLAB expression for PsychBench to evaluate during the experiment. The expression must evaluate to <cd>true<cd>/<cd>false<cd>, and the cue will only be met if true. If you need multiple lines of code, the expression can be the name of a script that makes a variable ans containing <cd>true<cd>/<cd>false<cd>.

An and expression can use the following variables:

response/responseBy cue:
response
correctResponse
responseScore
responseLatency
n_response

Response and information. Mostly taken from corresponding record properties of the response handler element that recorded the response. If the element records multiple responses, these are just for the current response. n_response is response number recorded (1, 2, 3, …). See below for examples of using these to set response feedback.

trigger/triggerBy cue:
trigger
n_trigger

trigger is trigger value, taken from record property trigger of the element that registered the trigger. If the element registers multiple triggers, this is just the current trigger.
 n_trigger is trigger number registered (1, 2, 3, …).

Examples: Correct/Incorrect response feedback

element.start.response = true
element.start.and = <cdsm>"responseScore = true"<cdsm>

→ start at any response scored <cdm>true<cdm>, typically meaning correct.

element.start.response = true
element.start.and = <cdsm>"responseScore = false"<cdsm>

→ start at any response scored <cdm>false<cdm>, typically meaning incorrect.

Waiting from a cue: Field timeFrom

You can add field timeFrom to any cue to tell PsychBench to wait from when the cue occurs (including field and, if you set it). Set to a number (sec).

Example

element.start.response = true
element.start.timeFrom = 2

→ start 2 sec from any response.

Multiple cues

You can set more than one start or end cue for an element. If so the element will start/end at whichever one occurs first (including field and, if you set it). To do this, just make start/end a struct array. You can add different and and timeFrom fields for each cue.

Example: Setting a maximum start time

element.start(1).response = true
element.start(1).timeFrom = 2
element.start(2).t = 10

→ start 2 sec from any response or 10 sec from trial start, whichever occurs first.

Timing deviation in cues

For all events in an experiment there is typically some small deviation between expected time and actual time you get during the experiment (e.g. due to finite frame rate, dropped frames, etc.). See also properties startBuffer/endBuffer below. All element timing cues go off the actual, not expected, times of the events they listen for. This can be an important consideration sometimes:

Example – Absolute/Relative timing

element.start.t = 0
element.end.t = 0.5

element.start.t = 0
element.end.duration = 0.5

→ Both these elements aim to start at 0 sec. Suppose both actually start at 0.017 sec. Then the end.t cue (relative to trial start) would still aim to end the element at 0.500 sec, but the end.duration cue (relative to element start) would aim to end it at 0.517 sec.

Synchronizing elements

To synchronize the start or end of different elements, just give them the same start or end cue. This works regardless of modality (visual, auditory, etc.). Note synchronized visual elements are physically constrained to start or end at the same screen refresh.

Specialized timing

Additional specialized timing options are available in some element types. For example, elements of type sequence can run other elements in an alternating sequence, e.g. in a change blindness experiment. See element type documentation for more information.

Debugging timing – pbLog.txt

PsychBench writes pbLog.txt in the MATLAB current folder to log all events during the experiment. This gives you an overview of when everything starts and ends, which can be helpful in figuring out mistakes. Times in this log are approximate. For precise times and all other information use experiment results output.

Time measurements

start/end tell the element when to run. To measure actual times during the experiment, see record properties startTime, etc. below.

startBuffer
endBuffer

Defaults: no start/end buffers

Ignore unless you need precise timing.

There are various potential sources of deviation between expected element start/end times and actual times you get during an experiment. One common type of deviation is delay caused by dropped frames, i.e. too much processing that your system needs to do at the time. If this occurs, you may be able to reduce or eliminate it by setting a start or end "buffer" for the element. To check, do a test run with element record properties start/endLatencyBufferable in experiment results output. If these properties record a value > 0, you can try setting startBuffer/endBuffer to a similar value (sec).

Setting a buffer tells PsychBench to expect the dropped frames and shift them from after the target start/end time to before it. This gives PsychBench the time it needs to process the start/end on schedule. Note this can't eliminate the dropped frames, so for example some processes will still pause for the duration of the buffer, including display animation (not necessarily visible if you only set a short buffer, e.g. 1 frame ≈ 17 msec). But it can eliminate the delay in start/end time.

For more information on timing precision and frames see Timing precision.

startTrialsFromTrigger

Default: don't start later trials from trigger

Set = <cd>true<cd> if you want to set later trials to start from a trigger the element registers. Then set trial object property start for later trials. Use this if you want to run multiple (or all) trials from a trigger, e.g. in a scanner experiment.

Regardless of whether this property = <cd>true<cd> or <cd>false<cd>, you can still use any trigger the element registers to cue elements in the trial (element properties start/end fields trigger/triggerBy above).

staircase

Default: don't staircase any properties of the element

You can use a staircase to set one or more numeric properties of the element by listing them here. Then instead of you setting the target property, PsychBench will set it based on the value of the staircase when the trial runs. You also need a staircase object to carry and step the staircase value across trials. The usual approach is to apply the staircase to the same property of a similar stimulus element in each trial.

staircase is a further struct that can have the following fields. Omit fields (or leave them = <cd>[]<cd>) to leave them at default. In unusual cases to staircase multiple properties of the element, make staircase a struct array, e.g. <cd>staircase(1).target = <cd> ..., <cd>staircase(2).target = <cd>...

Note you will get an error during the experiment if a property is staircased to a value that is impossible for it (e.g. a negative value for a property that must be positive). You need to set the parameters here and in the staircase object so this can't happen.

.target

A string that is name of an input property to staircase. Or you can staircase part of a property by including index in the expression, e.g. <cdsm>"size(2)"<cdsm> would staircase the second coordinate in property size . If you staircase part of a property, you can set the rest of it in your experiment script or leave it at default. Target must be numeric (not necessarily scalar).

.setExpr

Default: set target = staircase value

You can set setExpr to a string that is any MATLAB expression for PsychBench to evaluate to set the target. The expression must use the variable staircaseVal which will contain the staircase value (a number).

e.g.
Target must be an integer (and staircase value might not be)
→ <cdsm>"round(staircaseVal)"<cdsm>

If you need multiple lines of code, the string can be the name of a script that makes a variable ans containing value to set.

.min
.max

Default: no minimum/maximum target value

You can use these fields to set minimum and/or maximum target values. The staircase won’t step if it would set the target past these limits. Size of min/max must be single numbers or = size of target. See also staircase object properties min/max if it’s more convenient to set min/max at the staircase value (before transformation by setExpr above).

.setStaircaseExpr

Default: Don’t update staircase value

If you use setExpr and the target value the staircase sets (what the subject perceives) may not precisely correspond to the staircase value, use setStaircaseExpr to update the staircase value recorded in the staircase object. e.g. if setExpr = <cdsm>"round(staircaseVal)"<cdsm>, you would use setStaircaseExpr to update to the rounded value. This is important since the recorded staircase value can affect the next staircase value and threshold estimate.

Usage is like setExpr except the variable to use in the expression is targetVal, which will contain the target value.

Example

See here.

Input properties all objects have

report
info

Record properties all elements have

PsychBench uses record properties to record information during experiments. You can't set record properties but you can see them in experiment results using input property report.

startTime
endTime
duration
n_startFrame
n_endFrame
startLatencyBufferable
endLatencyBufferable

startTime and endTime record start/end times relative to trial 1 start (sec). If the element presents a stimulus, these generally = stimulus onset/offset times. If the element listens for input from a device, these generally = earliest/latest times input could be received. Note these properties record actual times during the experiment—to set timing, use input properties start/end above.

duration records end time − start time.

n_startFrame and n_endFrame record frame numbers in the trial for the first/last frames the element ran in. They are related to startTime/endTime as start time = first frame start time, end time = last frame end time ( = next frame after that start time). You can use these with trial object record properties frameRate, frameIntervals.

startLatencyBufferable and endLatencyBufferable are estimates of the part of delay from expected start/end time (sec) that might be reducible by setting a buffer in properties startBuffer or endBuffer above. Generally only for experiments where precise timing is important.

For more information on frames and timing precision see Timing precision.

trigger
triggerTime
d_triggerTime
numTriggers

Some elements can register triggers when they are running. In PsychBench a trigger is a flag an element raises that elements in the trial can start/end from (properties start/end fields 
trigger/triggerBy above) or later trials can start from (trial object property start). You can switch any response handler element to register inputs as triggers instead of responses from subject using property registerTrigger. A common example is using keyPress elements to receive sync signals from a scanner that arrive as keyboard inputs. Some elements that aren’t response handlers can register triggers too, e.g. portSender/Receiver elements.

trigger is a value representing the trigger registered. What trigger values can be depends on element type—see its documentation. They are often numbers.

triggerTime is time the trigger occurred relative to trial 1 start (sec).

d_triggerTime is uncertainty in trigger time (sec). Range = ± d_triggerTime. This is > 0 in the common case of an element that checks to receive a trigger once per frame, giving uncertainty = 1/2 the interval between checks (≈ 8 msec at 60 frames/sec with no dropped frames). Otherwise this property reports 0, but note this doesn’t include other sources of uncertainty which may be present in your system. For more information on frames and timing precision see Timing precision.

If the element registers multiple triggers then these properties become row vectors or cell arrays.

numTriggers is number of triggers registered by the element.