staircase

Experiments

staircase turns a contiguous block of trial rows into an adaptive up/down (staircase) procedure: after correct responses the experiment moves to later rows (“down”, typically harder), after incorrect responses to earlier rows (“up”, typically easier). The column value both names the staircase and configures it inline. Order the rows within the block by difficulty; each row is one difficulty level.

Syntax

Give the staircase a name and put that name in the cell of every row that belongs to it, for example detect. The rows must be next to each other in the file and ordered by difficulty.

Settings go after a colon on the first row of the staircase, each written as a name, a space, and a whole number:

staircase="detect: start 3 down 1 up 2 reversals 8"

Everything before the first : is the staircase’s name (the whole cell, when there is no :). All rows sharing that name form one staircase, running from the first such row to the last.

Settings are only read from the first row bearing the name; anything written on later rows of the same staircase is ignored. Every setting is optional, and the ones you leave out keep the defaults listed under Options.

Options

Param	Default	Meaning
group N	none	Staircases with the same group number are interleaved: at each step one of the group’s unfinished staircases is picked at random
start N	1	Which level of the block to start at, counting from 1
down N	1	Rows moved forward (later, harder) on a down step
up N	1	Rows moved backward (earlier, easier) on an up step
boost N	= down	Larger down step used until the first reversal, so good performers reach their level faster. Without it, pre-reversal down steps are the same size as down
correct N	2	Correct answers needed since the last move before a down step is taken
incorrect N	1	Incorrect answers needed since the last move before an up step is taken
reversals N	5	Staircase ends after this many direction changes
trials N	50	Staircase ends after more than this many trials

Until a move is triggered, the same row is shown again. The counters reset after every move.

A staircase ends when any of these happens: the number of reversals is reached, the trial budget is exceeded, or the next step would fall outside the staircase’s own rows. On the last trial of a staircase:

• if other staircases in the group are still running, the experiment continues with them;
• once the whole group is finished, it continues with the trial after the group’s last row. If there is no row after the group, the experiment stops with an error saying the last trial of the staircase group could not be found.

Defaults & missing values

Leave the cell empty on every row that is not part of a staircase: those rows run as ordinary trials. Leave the column out of the file entirely if no trial uses a staircase.

A staircase without a group setting belongs to no group and runs on its own.

A staircase cell can never fail to be read: any setting you spell differently is simply left at its default, and whatever stands before the first : becomes the staircase’s name.

Works with

• Randomization: staircase blocks are never shuffled. Any random or randomPick value on a staircase row is ignored, so the rows keep their file order and their difficulty ordering.
• key and scoring: steps are driven by whether each response was scored correct, so staircase rows need a scorable response (key or equivalent).
• if and then: a then destination that fires wins over the staircase for that step; otherwise the staircase decides the next row.
• Trial counter: staircase repetitions do not consume the sequential trial count, so a progress bar based on it stalls while a staircase runs.
• Results: a staircaseResult column is added to the output, marked 1 on each staircase’s final trial and carrying the staircase’s name.

Examples

Single 2-down/1-up staircase over rows of increasing difficulty, starting at the 3rd level:

type	stimFormat	stim1	key	staircase
test	.png	contrast_10	1	detect: start 3 down 1 up 1 correct 2 incorrect 1 reversals 8 trials 40
test	.png	contrast_9	1	detect
test	.png	contrast_8	1	detect
test	.png	contrast_7	1	detect
test	.png	contrast_6	1	detect

Two interleaved staircases (randomly alternated) forming one group:

type	stimFormat	stim1	key	staircase
test	.png	easyA	1	sc_a: group 1 start 1
test	.png	medA	1	sc_a
test	.png	hardA	1	sc_a
test	.png	easyB	2	sc_b: group 1 start 2
test	.png	medB	2	sc_b
test	.png	hardB	2	sc_b

Tips & gotchas

Caution

Settings are picked up anywhere in the cell, including inside the name. A name containing a setting word followed by a space and a number, such as my up 2 test, silently changes that setting. Keep names clear of the words group, start, down, up, boost, correct, incorrect, reversals and trials.

• Writing boost anywhere in the cell, even without a number after it, switches the boost off instead of leaving it equal to down: pre-reversal down steps become single steps.
• The boosted step size only applies until the first reversal or first up-move; after that the normal down step is used.
• Reusing a staircase name on rows that are not next to each other stretches the staircase over everything in between.
• When several staircases share a group, the next one is chosen at random at every step, not in turn.
• Stepping past the first or last row of the block ends that staircase rather than stopping at the edge. The out-of-range row is never shown: the next staircase in the group, or the trial after the group, follows immediately.

Common combinations

staircase appears in these worked recipes:

• Adaptive staircase: Home in on a participant’s detection threshold by making trials harder after correct answers and easier after misses.