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. In PsychBench you can run a staircase experiment by staircasing one or more properties of elements across trials.

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 with the command <type>Object, e.g. fixedStepStaircaseObject. Then sets its properties for staircase parameters, and add it with addToExperiment. (This is outside trials with addToExperiment because a staircase spans multiple trials.)

2. Target element objects

You can staircase one or more input properties of an element by listing them in element property staircase. Then instead of you setting the property, PsychBench will set it before the trial the element is in based on staircase value at the trial. Target properties must be numeric (not necessarily scalar). The general approach is to staircase the same property of a similar stimulus element in each trial in the staircase.

3. Response handler elements

After each trial in a 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 true/false (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. To do this just make and add multiple staircase objects. 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.

Trials not in a staircase

You can mix in any number of trials that don’t contain staircased elements. A staircase will not update its value or threshold estimate after such 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 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, i.e. all remaining trials in it will be skipped, after this many reversals (see reversed below). <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 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.