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 functions, 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).
Default: start = no start conditions → element doesn't run
Default: end = no end conditions → element must end on its own
Start/End the element at time relative to trial start (sec). 0 = trial start.
End the element at time relative to its start (sec).
Start/End the element when another element starts or ends 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>
Set field response = <cd>true<cd> to start/end the element at any response from subject recorded by any response handler element in the trial.
Or if there are multiple response handlers in the trial, you can use field responseBy instead to listen for any response recorded by a specific one. Set to a string/string array, like startOf/endOf 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.
Start/End the element at any trigger registered by any element in the trial. Usage is like response/responseBy above. See also field and below.
You can set also timing for whole trials from a trigger, e.g. in a scanner experiment. See trial object property start for this.
If you set field preTrial = <cdm>true<cdm>, the element runs in the pre-trial interval. Only simple static visual elements can do this (e.g. cross elements). Also currently you can only run one element in a pre-trial interval. Note to set pre-trial background color, use trial object property preTrialBackColor.
Some elements can end on their own—check Object ends on its own? near the top of the type documentation for if and when. For example, at default a keyPress element ends on its own when it records a response. If an element ends on its own, it's an automatic end condition which you don't need to set. That means you don't need to set property end for the element unless you want to maybe end it earlier.
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 condition is set, so the element needs to be able to end on its own.
You can add field and to some conditions (currently response and trigger conditions) 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 condition will only be met if <cd>true<cd>. 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 and related information. Mostly taken from corresponding record properties of the response handler element that recorded the response. Additionally n_response is response number recorded by the respond handler (1, 2, 3, …). Note if the response handler has recorded multiple responses, these variables contain information for the current one. See below for examples of using these to set response feedback.
trigger is trigger value, taken from record property trigger of the element that registered the trigger. n_trigger is trigger number registered (1, 2, 3, …). If the element has registered multiple triggers, these variables contains information for the current one.
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.
You can add field timeFrom = a number (sec) to any condition to tell the element to wait from when the condition is met (including and above if set) to start/end.
element.start.response = true
element.start.timeFrom = 2
→ start 2 sec from any response.
You can set more than one start or end condition for an element. If so the element will start/end at whichever one occurs first. To do this, just make start/end a row struct array instead of a single struct. Note additional fields (and, timeFrom, orAfter) can have different values for different conditions.
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.
By default each trial simply ends when no elements are left running or waiting to start at definite times (e.g. time conditions like t or duration or any condition with a timeFrom field). If none of an element's start conditions occur by then, it just won't run.
Another way for an element to maybe not run is to add field orAfter to an end condition. By default any end condition that occurs before the element would start is just ignored. However, if you add field orAfter = <cd>true<cd> then the element will not run any time at or after the condition occurs, regardless of the element's start conditions.
pic.start.t = 5;
pic.end.response = true;
→ pic starts 5 sec from trial start and ends at any response.
pic.start.t = 5;
pic.end.response = true;
pic.end.orAfter = true;
→ pic starts 5 sec from trial start and ends at any response. Additionally, if a response is recorded before the element starts (before 5 sec), it won't run.
To synchronize the start or end of different elements, just give them the same start or end condition. This works regardless of element modality (visual, auditory, etc.).
Additional special 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.
By default each trial simply ends when no elements in it are left running or waiting to start at definite times, and the next trial starts after a 0.75 sec interval. This is all you need for most experiments. However, see Trial timing if you need more information and trial object properties preTrialInterval, start, end for more options.
There are various potential sources of deviation between expected element times and actual times you get during an experiment—finite frame rate, dropped frames, inherent delays when starting/ending on spontaneous conditions (e.g. response and trigger conditions with no wait time added), etc. In experiments where precise timing is important, you may need to consider these, in some cases to be aware of them as limitations and in other cases to avoid them by setting things correctly. If precise timing is important, see Timing precision for more information. See also properties startBuffer/endBuffer below.
PsychBench writes pbLog.txt in the MATLAB current folder to log events like elements starting and ending during the experiment. This can be helpful for figuring out mistakes you made in setting element start/end conditions. Note times in this log are approximate. For all other purposes use experiment results output (see Time measurements above).
start/end tell the element when to run. To measure actual times during the experiment, include record properties startTime, endTime, duration, etc. below in experiment results output (property report). Similar record properties are available at the trial and experiment levels.
See the timing tutorial in <PsychBench folder>/docs/tutorials.
Defaults: no start/end buffers
There are various potential sources of deviation between expected element times and actual times you get during an experiment. One common 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). Buffering is only possible for start/end conditions that have definite times so PyschBench can plan ahead (t conditions, duration conditions > 2 frames, any condition with a wait time timeFrom > 2 frames).
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 actually prevent the dropped frames. 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 prevent the delay in start/end time.
For more information on timing precision and frames see Timing precision.
Default: don't allow subsequent trials to start from trigger
Regardless of this property, you can use triggers the element registers to cue elements in the same trial (element properties start/end fields trigger/triggerBy above).
Default: don't vary any properties of the element
You can only vary properties that are adjustable. Which properties are adjustable depends on the element type—see the top of the property list in its documentation. If you need to make other properties adjustable, you can edit the element type code—see Element Type Programming Manual.
vary is a further struct that can have the following fields. In unusual cases to vary multiple properties of the element, you can make vary a struct array, e.g. <cd>vary(1).target = <cd> ..., <cd>vary(2).target = <cd>...
A string that is name of an input property to vary. You can also vary part of a property by including further indexes/field names, e.g. <cdsm>"size(2)"<cdsm> would vary the second coordinate in property size . If you vary part of a property, you can set the rest of it directly or leave it at default.
If you want to vary a visual element property that you set in units other than deg using <cdm>{val, <cdm><cdsm>"unit"<cdsm><cdm>}<cdm> form, just target the numeric part of the property here, e.g. <cdsm>"height{1}"<cdsm>.
A string that is any MATLAB expression for PsychBench to evaluate to set the target. The expression can use the variable t which will contain current time relevant to element start (sec). 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.
element.vary.target = <cdsm>"position"<cdsm>
element.vary.setExpr = <cdsm>"[-5+mod(2*t, 10) sin(pi*t)]"<cdsm>
→ move a visual element right on a sinusoidal path and wrap around
element.position = {[], <cdsm>"cm"<cdsm>};
element.vary.target = <cdsm>"position{1}"<cdsm>
element.vary.setExpr = <cdsm>"[-5+mod(2*t, 10) sin(pi*t)]"<cdsm>
→ same but in cm instead of deg
Default: don't staircase any properties of the element
staircase is a further struct that can have the following fields. You can omit fields (or leave them = <cd>[]<cd>) to leave them at default. In unusual cases to staircase multiple properties of the element, you can 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.
No default
A string that is name of an input property to staircase. You can also staircase part of a property by including further indexes/field names, 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 directly or leave it at default. Target must be numeric (not necessarily scalar).
If you want to staircase a visual element property that you set in units other than deg using <cdm>{val, <cdm><cdsm>"unit"<cdsm><cdm>}<cdm> form, just target the numeric part of the property here, e.g. <cdsm>"height{1}"<cdsm>.
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.
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. min/max can be single numbers to apply to all numbers in target, or numeric arrays with size = size of target. If you target part of a property, min/max applies only to that part.
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).
Default: Don’t update staircase value
If you use setExpr above 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 staircased target value.
See here.
PsychBench uses record properties to record information during experiments. You can't set record properties but you can see them in experiment results by listing them input property report.
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 frameRates, 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.
In PsychBench a trigger is a flag an element raises when it's running that any elements in the trial can start/end from (properties start/end fields trigger/triggerBy above) or subsequent trials can start from (trial object property start). Only some elements can register triggers: You can switch any response handler element to register inputs as triggers using its 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 also register triggers, e.g. portSender/Receiver elements.
If the element can register triggers:
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.
PsychBench © 2017–2023 Giles Holland
Website © 2023 Giles Holland
End user license agreement