In a staircase experiment a staircase value (a number) carried across trials determines some stimulus parameter at each trial. Staircase value can then step up or down for the next trial based on whether response from subject was correct, making the task harder (correct) or easier (incorrect) and so adapting to the subject’s threshold.
A staircase experiment is the interaction of a staircase object, target element objects, and response handler element objects. Any staircase object can staircase any properties of any elements and get correct/incorrect from any response handler elements.
You need one staircase object to carry and step the staircase value across trials. There are different staircase object types allowing for different methods, e.g. fixedStepStaircase and questStaircase. You can add columns setting properties for a staircase object in the optional table for objects not specific to trial (experiment, device, staircase objects). [Or in the coding method: Make a staircase object outside trials using function <><type><>Object, e.g. fixedStepStaircaseObject, set properties, and input it to addToExperiment.]
For any element, you can use the staircase to set one or more numeric input properties by listing them in property staircase, which all elements have. Then instead of you setting the target property, PsychBench will set it based on the value of the staircase when the trial containing the element runs. The usual approach is to apply the staircase to the same property of a similar stimulus element in each trial.
After each trial in the staircase, it needs to get whether response was correct to know whether and which way to step its value. It does this automatically from any response handler element in the trial that scored a response <cd>true<cd>/<cd>false<cd> (response handler property scoreResponse, record property responseScore). If there is more than one response handler in the trial you can specify which one(s) to look to using response handler property scoreResponseForStaircase.
Some experiment designs involve staircasing one element relative to another element in each trial, e.g. staircasing the difference between two elements. To do this, set the property of one element directly, then staircase the property of the other element relative to the first one using element property staircase field setExpr. See <><PsychBench folder><>/docs/demos/staircaseDemo for an example.
You can run multiple staircases in an experiment, consecutive or interleaved. To do this, set multiple staircase objects for the experiment. Then for each trial in a staircase, set trial object property withStaircase to specify which staircase to use. Each staircase will carry its value independently and will only update its value and threshold estimate after trials it’s used in. Note each trial can only be in one staircase.
You can mix in any number of trials that don’t contain staircased elements. Staircases won't update their values or threshold estimates after those trials.
You can also have trials that don’t contain staircased elements but are still associated with a staircase such that they will be skipped if they would run after the staircase ends (e.g. from property maxNumReversals below). To do this, again use trial object property withStaircase. The trial will not actually be in the staircase, i.e. the staircase will still not update its value or threshold estimate after the trial.
See multiple staircase demos in <><PsychBench folder><>/docs/demos.
Defaults: no minimum/maximum staircase value
You can use these properties to set minimum and/or maximum staircase values. The staircase won’t step if it would step past these limits. See also element property staircase fields min/max if it’s more convenient to set min/max at the target (after transformation by field setExpr).
Default: no maximum number of reversals
The staircase will end after this many reversals (see reversed below). All remaining trials in it will be skipped. Any trials not in the staircase will simply bump forward as needed, i.e. skipped trials don't leave gaps. <cd>inf<cd> = no limit.
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.
Staircase value (a number) for the trial. The staircase sends this to any target elements in the trial (element property staircase). Target elements can transform and correct it—see property staircase fields setExpr, setStaircaseExpr. The final staircase value after correction is recorded here and the staircase uses it to update its estimate in threshold (below).
<cd>true<cd>/<cd>false<cd>: response the staircase listened to in the trial was correct.
<cd>true<cd>/<cd>false<cd>: staircase reversed after the trial. A reversal is where the staircase steps in the direction opposite to its previous step. Note if the staircase would step but does not because a staircased element property is at its minimum/maximum value, it still counts as a step for reversals.
Estimate of threshold after the trial. This is in staircase value units, same as val above. Generally the value for the last trial in the staircase is the one you want.
numTrialsRan is number of trials in the staircase that have run.
numReversals is number of trials where the staircase has reversed.