All staircase objects

In an adaptive staircase experiment a staircase value (a number) at each trial determines some stimulus parameter. Staircase value can then step up or down after the trial based on whether response from subject was correct, making the task harder (correct) or easier (incorrect) in the next trial in the staircase and so adapting to the subject’s threshold.

Staircase object + Target elements + Response handler elements

A staircase experiment is the interaction of a staircase object, target element objects, and response handler element objects across trials. Any staircase object can staircase any properties of any elements and get correct/incorrect from any response handler elements—this modular approach allows a lot of flexibility.

1. Staircase object

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. fixed step and QUEST. In an experiment script make a staircase object outside trials using function <type>Object, e.g. fixedStepStaircaseObject, set its properties for staircase parameters, then add it using addToExperiment. (This is outside trials because a staircase spans multiple trials.)

2. Target element objects

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 runs. The usual approach is to apply the staircase to the same property of a similar stimulus element in each trial.

3. Response handler elements

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.

Staircasing an element relative to another element

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 example below.

Multiple staircases

You can run multiple staircases in an experiment, consecutive or interleaved. However, each trial can only be in one staircase. To do this, make and add 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.

Trials not in a 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.

Control 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, e.g. the staircase will still not update its value or threshold estimate after the trial.

Example 1. Staircasing an element

This is the skeleton of an experiment where each trial shows a linear dot mask with number of dots staircased using a fixed step staircase. Initial number of dots = 300. Minimum number of dots = 0.


mask = linearDotMaskObject;
mask.start.t = 0;
mask.end.duration = 0.5; = <cdsm>"numDots"<cdsm>;
mask.staircase.min = 0;

<rm><Make other objects for trial, including a response handler><rm>

addTrial(mask, <other objects>);

staircase = fixedStepStaircaseObject;
staircase.val1 = 300;
<rm><Set other staircase properties><rm>

<rm><Set trial list and run experiment><rm>

Example 2. Staircasing an element relative to another element

See the staircase tutorial in <PsychBench folder>/docs/tutorials for an experiment where each trial shows two pictures. Each picture shows for 0.5 sec, with 0.5 sec between them. One is rotated at a random angle. The other is rotated at that angle minus some difference, and the difference is staircased.

Input properties all staircase objects have


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.​

Input properties all objects have


Record properties all staircase objects have

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.


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.