random

Experiments Surveys & forms

Shuffles the presentation order of a run of consecutive trials. Use it when trials within a section of the trial file should appear in a different random order for each participant, while everything outside the marked run keeps its position.

Syntax

Put 1 in the cell of every row you want shuffled: consecutive rows with the same value shuffle among themselves, and rows with an empty cell keep their position.

The value acts as a run tag, not an on/off switch. Runs are built from consecutive rows:

• A run starts where the value changes from empty to anything else, and ends where it changes back to empty.
• Two adjacent runs with different values (e.g. 1 then 2) shuffle separately: a value change closes one run and opens another.
• A run also breaks, even with an unchanged value, when the randomBlock value differs between neighbours or the trial’s timer label differs.

Conventionally 1 is used, but any non-empty value marks the row; only whether it matches the neighbouring rows matters.

The cell holds nothing but that tag. The sampling and ordering specs that random briefly accepted (1: sample 10, 1: maxRun 3 difficulty) now live in the trialOrder column, so a colon in a random cell is an invalid value: it is refused when the trial file is saved, and again when the experiment is built. The error names the conversion, for example move the group to trialOrder as "1: shuffle".

Options

Value	Effect
empty cell	Trial keeps its position; acts as a fixed boundary between shuffle runs
any other token (1, 2, A, even 0)	Trial joins the shuffle run of consecutive rows with the same token (and same randomBlock + timer label)

There is no “off” value other than an empty cell. random=0 enables shuffling, because 0 is a non-empty value.

Defaults & missing values

• When the column is absent or a cell is left blank, the trial keeps its position.
• Shuffling is skipped entirely when no cell in the column carries a value; a single non-empty cell anywhere activates it.
• Trials with a non-empty staircase cell are never shuffled.

Works with

• trialOrder: the two columns cannot be used in the same file. trialOrder owns the ordering story, so a random cell that carries a group value next to it is refused both when the trial file is saved and when the experiment is built, with a message that prints the conversion: move random group 1 to trialOrder as "1: shuffle".
• randomBlock: the full randomBlock value bounds each shuffle run. Within-block shuffling runs before between-block shuffling.
• timer (label option): trials under different timer labels never shuffle together.
• randomPick: when the randomPick column carries values, the initial random/randomBlock pass is skipped entirely; shuffling is applied only after picking (within blocks first, then between blocks), and a pick error halts the experiment with an error page. random is also part of the legacy pick-pool grouping.
• staircase: staircase trials are never shuffled.
• rules / block: block/rules reorder the trial list before random is applied, so random operates on the post-rules order.
• Advanced randomness: when the project’s advanced randomness setting is on, each run’s shuffle order is fetched from random.org, falling back to the local random generator.

Examples

Shuffle three test trials, keep the instruction screen first:

type	stim1	stimFormat	random
instructions	intro
test	a	.png	1
test	b	.png	1
test	c	.png	1

Two independently shuffled sets, adjacent in the file (value change splits the runs):

type	stim1	stimFormat	random
test	a1	.png	1
test	a2	.png	1
test	b1	.png	2
test	b2	.png	2

Contain shuffling inside blocks (same random value, randomBlock change breaks the run). Note that a non-empty randomBlock also triggers the between-block pass, so the two blocks additionally swap order as wholes:

type	stim1	stimFormat	random	randomBlock
test	a1	.png	1	1
test	a2	.png	1	1
test	b1	.png	1	2
test	b2	.png	1	2

Tips & gotchas

Caution

random=0 randomizes. Only an empty cell disables shuffling; if you expect 0 to mean “off”, you will get shuffled trials.

• The type column is not a run boundary in the plain shuffle: a random=1 run spanning an instructions row and test rows shuffles the instruction screen into the mix. type only bounds pools in the randomPick pipeline.
• Grouping is strictly positional: trials with the same random value separated by a row with an empty cell form two independent runs.
• A single non-empty cell anywhere in the column activates shuffling; only a fully empty column keeps every trial in place.
• Rules plus labeled timers misalign. When block/rules reorder or shrink the trial list, the timer-label boundaries can be applied to the wrong rows. Avoid combining block/rules sampling with labeled timers and random.
• A colon in a random cell is an error. The cell takes a plain group tag, so any value containing : is rejected when the trial file is saved and again when the experiment is built, with a message pointing at the trialOrder column. One leniency survives at build time: a stored legacy clock-like value (e.g. 12:30, 1:30 min) is still treated as an opaque run tag so running studies keep working; re-saving that file rejects it.

Common combinations

random appears in these worked recipes:

• Likert block in random order: Present a block of likert questions in a fresh random order per participant, with the answer options in a fixed order.
• Between-subject conditions: Give each participant one of two stimulus sets, while shared screens run for everyone.
• Counterbalanced key mapping: Give half the participants one response-key mapping and half the reversed mapping, with matching instructions for each.