Trial Sequencing

The trialOrder column controls which trials a participant receives and in what order. It replaces ad hoc combinations of the legacy random and randomPick columns with one small language that covers constrained randomisation, sampling, ordered selection, structured shuffles, and reusable orders. Everything runs per participant, and the editor checks every instruction as you type, so an impossible design is caught while you build it, never in front of a participant.

Groups and programs

Write a program on one row of a group, and the bare group number on the group’s other rows:

trialOrder = 1: shuffle; maxRun 2 condition
trialOrder = 1
trialOrder = 1

All rows sharing the number form the group. Rows with an empty cell, 0, or na never move. Each numbered group runs its own program independently.

Tip

Trials stay in trial file order until a word says otherwise. A group that should simply be randomised must say so: 1: shuffle is the classic randomised order.

The two axes

Every word answers one of two questions:

• Selection, which trials appear: sample, select, groupSample, groupSelect
• Ordering, where they go: shuffle, the constraints (maxRun, noRepeat, alternate, gap, balance, pattern, first, last, follows, notFollows), structure (groupShuffle, shuffleWithin), and reuse (saveOrder, useOrder)

The selection words always choose at random; they differ only in how the survivors are presented. This table is the heart of the system:

spec	which trials are chosen	rest of the group	presentation
shuffle	all stay		random
sample 5	random 5 from the group	dropped	random
sample 5 difficulty	random 5 per value of difficulty	non-selected dropped	random
sample 5 difficulty easy	random 5 among easy only	all non-easy trials stay	random
select ... (same three forms)	same choice rules as sample	same	file order
groupSample 2 pair	2 random whole units	other units dropped	unit order random, inside each unit file order
groupSelect 2 pair	2 random whole units	other units dropped	everything file order
groupShuffle pair	all stay		unit order random, inside each unit file order

A memory aid: sample shuffles what it keeps, select keeps your order. The same pair exists at the block level (block.sample and block.select) with the same meanings.

Constraints ride on a shuffle

Constraint words describe which random orders are acceptable, so they need randomness to constrain. Add shuffle, or use sample or groupSample, whose meaning already includes it:

trialOrder = 1: shuffle; maxRun 2 condition
trialOrder = 1: sample 10 difficulty; maxRun 1 difficulty

constraint	meaning
maxRun 2 condition	never more than 2 consecutive trials sharing a condition value
noRepeat item	the same value never appears twice in a row
alternate difficulty	strict alternation between the values
gap 2 4 item	2 to 4 other trials sit between two appearances of the same value (gap 2 item means at least 2, no upper limit)
first 2 category filler	the group opens with 2 filler trials
last 1 category target	the group closes with a target trial
balance 4 difficulty	every window of 4 trials holds each value in proportion to its share
pattern phase stim stim question	positions tile a fixed skeleton; * is a free slot
follows category prime category target	every prime is immediately followed by a target
notFollows condition con condition inc	a con trial is never immediately followed by an inc trial

first and last also work without any shuffle, pinning trials to the edges of an otherwise file-ordered group.

Note

gap counts the trials between two appearances, not the distance between their positions. gap 0 item allows immediate repeats.

Structure and reuse

• groupShuffle unit moves trials sharing a unit value as one chunk; chunks shuffle, the order inside each stays as in your file. Ideal for yoked pairs (a prime always directly before its own target).
• shuffleWithin unit is the mirror image: chunks stay put, trials shuffle inside them.
• saveOrder name remembers a group’s realised order; useOrder name in a later group of the same size replays the same relative order. Ideal for study and test phases that must share a sequence.

Factorial designs

Join two columns with * and each combination counts as one condition:

trialOrder = 1: sample 1 valence*arousal
trialOrder = 1: shuffle; maxRun 1 valence*arousal

The first keeps one trial per cell of the design; the second stops the exact combination repeating back to back. Crossing works in sample, select, groupSample, groupSelect, maxRun, noRepeat, and balance.

Rules worth knowing

• One program per group, on any single row of the group.
• Structure words cannot combine with constraints, and select/groupSelect cannot combine with anything that would reorder their file-order promise. The editor names any offending pair.
• A group spanning several randomBlock values, trial types, or timer sections applies its program inside each part separately.
• The legacy random column keeps working in old experiments but cannot mix with trialOrder in one file. Convert a legacy group 1 to 1: shuffle. Replace randomPick N with sample N.

Next steps

• Randomisation (legacy columns) — the classic random, randomBlock, and randomPick columns
• Between-Subject Experiments — assign participants to fixed groups
• Project Flow and Trial Management — breaks, repeats, and rules