trial objects

An object of type trial provides some options and record properties for a whole trial. In trial definition tables you can add columns setting properties for one trial object per trial definition (row). [Or in the coding method: Make a trial object using function trialObject, set properties, and input it along with element objects to addTrial.]

Trial timing

By default each trial ends whenever no elements in it are left running or scheduled to start. You can optionally add further end conditions in trial object property end. The next trial to run then starts after an interval which you can change in trial object property preTrialInterval (default = 0.75 sec). In this mode trial start and end times are flexible, which is okay for most experiments.

You can also set trials to start at fixed times relative to experiment sync in a past trial using trial object property start field t_sync, e.g. in a scanner experiment.

Either way, trial repetition and order is set in your trial list. (Optionally you can set it directly in trial definitions instead but usually that's harder.)

preTrialInterval

Default, changeable in pb_prefs: 0.75 sec

preTrialInterval sets (minimum) time from previous trial end to this trial start (sec). By default the pre-trial interval is just a blank screen. You can change its background color using preTrialBackColor below. You also can show a static visual element in it by setting the element’s start field preTrial = <cd>true<cd>. The most common example is a cross object for a fixation cross. See also record properties preTrialInterval_r and preTrialHeadroom below.

PsychBench always needs some time between trials to close the previous trial and prepare the next one. How much time depends on what elements you run and your system. If preTrialInterval is too short for this, PsychBench will automatically extend the interval and the experiment time course will bump forward, with a warning at the MATLAB command line. This is okay in most experiments (the main possible exception is scanner experiments—see start below). If not okay, you can increase preTrialInterval to get a consistent length, or use experiment/trial/element property preload to allow for shorter lengths.

preTrialBackColor

Default, changeable in pb_prefs: same as trial

A 1×3 RGB vector with numbers between 0–1 setting background color for the pre-trial interval. Default is same as trial, which you can set in backColor below.

backColor

Default, changeable in pb_prefs: same as experiment

A 1×3 RGB vector with numbers between 0–1 setting background color for the trial. Default is same as experiment, which you can set in experiment object property backColor (default black). You can override this for any part of the trial using a backColor element.

start

Default: trial starts flexibly whenever previous trial ends + pre-trial interval

Use trial start.t_sync in experiments where you need precise timing across multiple (or all) trials relative to a sync point, e.g. scanner experiments that run trials from a sync. (Note if you re-sync in each trial, you don’t need to use trial start.t_sync. Just set element timing using element properties start/end.t_sync, which go off the sync in the element's trial.)

By default a trial starts flexibly whenever the previous trial ends + pre-trial interval (above). Alternatively if you use property start, the trial starts at a fixed time relative to experiment sync in a past trial. To do this, first use an element in one trial (a "syncer" trial) to sync the experiment at a trigger it registers using element property syncExperiment. Then for any number of trials that run subsequently, set trial object property start for start time relative to that sync. start is a further struct with one field start.t_sync containing a 1×2 vector <cd>[t0 dt]<cd>. It works conditionally, so you can set it the same for all the subsequent trials:

1. <cd>t0<cd> = start time relative to sync (sec) if this is the first trial that runs after the sync
2. <cd>dt<cd> = start time increment (sec) if this is a later trial

Setting trial start.t_sync does three things:

• If you did not set start.t_sync (default flexible trial timing) then even if you set your trials to run for specific durations based on the elements in them, deviations in timing on the order of milliseconds can accumulate to cause drift in later trial start times. Setting start.t_sync prevents this.
• If the previous trial ends early then this trial will wait to start on time.
• If the previous trial would run late then it will end so this trial's pre-trial interval starts on time. This also applies to this trial if it is the last in a sequence of trials with start.t_sync set. i.e. the last trial in an experiment or in a block of fixed time trials still ends this way.

Notes

• You can sync once for the experiment or re-sync any number of times. A trial with start.t_sync set goes off the most recent sync.
• If a trial has start.t_sync set but the experiment is not synced, it defaults to starting flexibly. This happens if no element has synced the experiment yet. It also happens if the experiment was synced but then a trial with no start.t_sync (flexible timing) ran, which cancels the sync.
• If you set trial start.t_sync, it’s important that pre-trial interval is long enough for the processing PsychBench needs to do between trials. If it isn’t, the trial will start late regardless of start.t_sync. Change preTrialInterval above if needed. You can also use experiment/trial/element property preload to allow for shorter pre-trial intervals.

end

Default: trial ends when no elements are left running or scheduled to start

You can add further end conditions for the whole trial here. Usage is the same as element property end: this is a further struct with possible fields setting different conditions for the trial to end (e.g. time, duration, response from subject, etc.), or a row struct array for multiple end conditions. You can use the same fields as for element end. If an end condition for the trial occurs, all running elements end and the next trial's pre-trial interval begins.

withStaircase

Default: automatic if trial contains staircased elements and experiment contains only one staircase

Usually you can leave withStaircase at default, including in most staircase experiments with only one staircase.

If you’re running an experiment with more than one staircase, for each trial that contains staircased elements, you must set withStaircase to specify which staircase to use for the trial.

You can also set withStaircase for a trial if it doesn’t contain staircased elements but you want to associate it with a staircase such that it will be skipped if it would run after the staircase ends. The trial will not actually be in the staircase, e.g. the staircase will not update its value or threshold estimate after the trial.

withStaircase is a string pointing to a staircase object by its variable name and possibly index, e.g. <cds>"staircase"<cds>, <cds>"staircases(2)"<cds>, etc. (In the visual method you can specify a name/index for an object in its object heading, default = object type name. In the coding method it's just the variable name you use in the experiment script.) Each trial can only be in or associated with one staircase. See link above for staircase objects.

preload

Default, changeable in pb_prefs: same as experiment

Sets preload for all elements in the trial. This overrides experiment object property preload in the trial—see there for more information.

profilerFileName

Default, changeable in pb_prefs: don't run MATLAB profiler

(Element type code debugging)

If you set this, PsychBench will run the MATLAB profiler at the trial so you can profile execution time of element type code there, including open/run/close code. You can set profiler options directly using the profile command before running the experiment. At least as of MATLAB R2021a, you can input a profiler results struct to the command profview to view it—type help profview at the MATLAB command line for usage but e.g. <cd>profview(0, <cd><resultsStruct><cd>)<cd>.

profilerFileName is a string that is name of .mat file to save profiler results to. You can optionally include path. If you don't, it saves in the MATLAB current folder. You can use the same file for multiple trials in an experiment—PsychBench will append results in an array in the file.

n_def
n

n_def is trial definition number/label. This is before any order and repetition if you use a trial list. By default PsychBench automatically numbers trial definitions 1, 2, 3 ... in the order they are defined. You can also use custom numbers or strings (visual method: in a column before objects with no headings / coding method: in an input to addTrial).

n is trial number during the experiment.

preTrialInterval_r
preTrialHeadroom

preTrialInterval_r records time from previous trial end to this trial start (sec). Note this property records the actual interval during the experiment—to set interval, use input property preTrialInterval above.

preTrialHeadroom is time left in the set pre-trial interval when PsychBench completed the processing it needed to do between the trials (sec). < 0 means preTrialInterval was set too short and the interval extended.

startTime
endTime
duration

startTime and endTime record start/end times relative to trial 1 start (sec). These = offset of inter-trial interval at trial start and onset of inter-trial interval at trial end, both at screen refresh. If the trial starts/ends with visual stimuli, these also = those stimulus onset/offset times.

duration records end time − start time.

frameRates
frameIntervals

frameRates is a row vector recording instantaneous frame rates across all frames in the trial, indexed by frame number. At each frame, the frame rate is calculated as 1 / frame interval (frame/sec).

frameIntervals is the corresponding row vector of all frame durations (sec).

frameRates can be used to get a sense of the actual frame rates achieved during the trial, which nominally = screen refresh rate (screen object record properties refreshRate, refreshInterval) but can be lower when frames are dropped due to processing load. Additionally, both properties can be used with element record properties n_startFrame and n_endFrame—for example, you can check if a dropped frame delayed an element start by checking for decreased rate or increased interval at the frame before n_startFrame. For more information on frames see Timing precision.