Trial objects are optional. You only need to add them if you want to change a property from default. Note for some properties you can also change the default values themselves using pb_prefs at the MATLAB command line, which may be more convenient.
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.]
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 typically set in your trial list. For unusual cases you can set it directly in trial definitions instead.
Default: 0.75 sec
PsychBench always needs some time in each pre-trial interval to close the previous trial and prepare this one. How much time depends on what elements you run and on your system. If preTrialInterval is too short, PsychBench will automatically extend the interval and the experiment time course will bump forward. This is okay in most experiments.
Default: 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.
Default: 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. You can override this for any part of the trial using a backColor element.
Default: trial starts flexibly whenever previous trial ends + pre-trial interval
Setting trial start.t_sync does three things:
Use trial start.t_sync in experiments where you need precise timing across trials relative to a sync, e.g. scanner experiments that run multiple or all trials from a sync. (Note if you re-sync in each trial, you don’t need to use trial start.t_sync. Just set timing of elements from the sync in their trial using element properties start/end.t_sync.)
See scanner demos in <><PsychBench folder><>/docs/demos.
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.
trial.end.response = true;
trial.end.and = <cdsm>"response == 2"<cdsm>
→ end all elements and the trial if the subject inputs a response = 2.
Default: automatic if trial contains staircased elements and the experiment contains 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 (visual method: in its object heading / coding method: in the experiment script). e.g. <cds>"staircase"<cds>, <cds>"staircases(2)"<cds>, etc. Each trial can only be in (or associated with) one staircase. Tip: If you have an index in a numeric variable you can use it in an <cds>"x"<cds> string (but not an <cds>'x'<cds> string) like this: <cds>"pictures("<cds><cd> + n + <cd><cds>")"<cds>. See link above for staircase objects.
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.
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 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 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 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.