trialOrder

Experiments Surveys & forms

trialOrder decides which trials a participant gets and in what order. A cell marks a row as part of a numbered group, and one row of that group carries the group’s program: a short line of words such as 1: shuffle, 1: sample 20 difficulty or 1: shuffle; maxRun 2 condition1. Use it to shuffle a stretch of trials, to keep only part of a long item set, to hand different participants different conditions, and to demand structure of the random order (no long streaks of one condition, a minimum lag between repeats of an item, a fixed opening trial, a balanced window, a prime always followed by its probe). Rows left blank stay exactly where they are, so instruction screens and practice blocks keep their place without any extra marking.

The program has two axes: SELECTION decides which trials appear (sample, select, groupSample, groupSelect), ORDERING decides where they go (shuffle, groupShuffle, shuffleWithin, the constraints, and the saveOrder/useOrder order bank). The one line to remember: sample shuffles what it keeps, select keeps your order.

trialOrder replaces the older sequencing columns. The legacy random column is plain group numbers again and cannot appear next to trialOrder in one file, and randomPick/trialGroup are replaced by the selection words.

Syntax

Put 1: shuffle on one row of the stretch you want randomised and a bare 1 on the other rows of that stretch. Those trials then appear in a random order, and everything else in the file stays where it is.

A cell is one of four things:

• empty, or 0 — the row takes part in no group. It keeps its trial-file position, and it closes the group of the rows above it.
• a whole number N — a membership row of group N.
• N: word or N: word; word; ... — the group’s program. The colon comes straight after the number and ; separates the words. A colon with nothing after it is an error.
• anything else — rejected: "abc" is not a valid trialOrder value.

A group is a run of consecutive rows carrying the same number. A row with a different number, or a row that takes part in no group, closes the run and opens a new one. So the same number used in two separated stretches makes two independent groups, each of which needs its own program.

Exactly one program per group, on any row of the group. The program does not have to sit on the first row of its group. Two rows of one group carrying different program text is an error (conflicting specs inside one trialOrder group); repeating the same text is tolerated.

Caution

A numbered group with no program anywhere is an error, not a silent no-op: trialOrder group 1 has no program; add "1: shuffle" for the classic randomised order. This is the deliberate difference from the old random column, where a bare number meant “shuffle”.

Keyword spellings. Keywords match case-insensitively, and every camelCase word also accepts its hyphenated form (group-sample, max-run, no-repeat, group-shuffle, shuffle-within, not-follows, save-order, use-order). Column names are matched case-insensitively against the columns in your file.

Argument order is number-first everywhere. Two forms changed from the older random-column grammar, and the old spellings now fail with the correction:

• gap MIN [MAX] column (was gap column MIN MAX): gap condition 1 3 fails with gap takes its numbers first: ... (expected: gap MIN [MAX] column, like "gap 2 5 condition").
• balance N column (was balance column N): balance condition 2 fails with balance takes its number first: ... (expected: balance N column, like "balance 4 condition").

first/last take their optional count in the same place, and writing it last is caught by name: "first condition a 2": the number goes right after first, like "first 2 condition a".

Crossing two columns. A column token may cross columns with *: difficulty*intensity reads the pair of cells as one composite value, so a 2x2 design has four values instead of two plus two, and value literals spell out one part per component (easy*low). Only sample, select, groupSample, groupSelect, maxRun, noRepeat and balance understand a crossed token; any other word reads the whole token as a single column name and then reports that no such column exists. A literal with the wrong number of parts is rejected: the value "easy" must have one part per crossed column ("difficulty*intensity"), like "easy*low".

Options

Cell values:

Value	Effect
empty cell / 0	The row is in no group: it keeps its trial-file position and closes the group above it
N (1 or higher)	Membership row of group N
N: word[; word ...]	The group’s program; exactly one row per group carries it, and it may be any row of the group
0: ...	Rejected: trialOrder group 0 is not a group
anything else	Rejected as an invalid trialOrder value

Selection words. The choice is ALWAYS random; the two families differ only in how the survivors are presented (sample shuffles what it keeps, select keeps your file order):

Word	Which trials are kept	Order of the survivors	The rest of the group
sample N	N drawn at random from the whole pool	shuffled	dropped
sample N col	N drawn per distinct value of col	shuffled	non-drawn tagged rows dropped, rows with no value in col kept
sample N col val	N drawn among the rows where col = val	shuffled	every row not carrying val is kept
select N / select N col / select N col val	identical draws to the three sample forms	trial file order	identical to the matching sample form
groupSample N col [val ...]	every row of N randomly chosen values of col	chosen units in random unit order, file order inside each unit	rows of non-chosen candidate values dropped; rows with no value, and rows of values not listed after the column, are kept
groupSelect N col [val ...]	identical choice to groupSample	everything in trial file order	identical to groupSample

Ordering words:

Word	Form	Effect
shuffle	shuffle	Randomise the group’s trials among their own positions. Takes no arguments
groupShuffle	groupShuffle col	Whole units (the rows sharing a value of col) swap places; file order kept inside each unit
shuffleWithin	shuffleWithin col	The units stay where they are; trials shuffle inside each one, so the sequence of values across positions is unchanged
saveOrder	saveOrder name	Bank the order this group ends up in, under name
useOrder	useOrder name	Replay a banked order onto this group; must be the only word in its group and the group must hold as many trials as the saved one

Constraints (all of them shape a randomised order; see the shuffle requirement below):

Word	Form	Effect
maxRun	maxRun N col [val]	At most N trials of the same value back to back; the value form limits only that value
noRepeat	noRepeat col [val]	The same as maxRun 1 col [val]: two equal values never touch
alternate	alternate col	The values of col take strict turns: the tagged trials follow one cyclic pattern of all distinct values
gap	gap MIN [MAX] col	MIN and MAX count the OTHER trials between two successive trials of the same value, so gap 0 allows adjacent repeats and a missing MAX means “no upper limit”
balance	balance N col	N is the window size: every full window of N trials holds each value in proportion to its share of the pool; the trailing partial window is unconstrained
first	first [N] col val	The first N trials (default 1) carry val
last	last [N] col val	The last N trials (default 1) carry val
pattern	pattern col v1 v2 ...	The skeleton tiles over the whole group: position i demands v[i % length]; * is a slot any trial may fill
follows	follows colA valA colB valB	Every trial matching the first pair is IMMEDIATELY followed by a trial matching the second; an antecedent in the last position violates
notFollows	notFollows colA valA colB valB	No trial matching the second pair may sit right after one matching the first

Caution

A constraint needs a randomiser in the same cell. A constraint describes which random orders are acceptable, so its group must also carry a randomising word: shuffle, or a sample/groupSample (whose meaning already includes the shuffle). 1: maxRun 2 condition1 alone is an error whose message prints the corrected line: maxRun constrains a shuffle, so write "1: shuffle; maxRun 2 condition1". first and last are the exception: with a randomising word they pin the edges of a shuffled order, without one they pin the edges of an otherwise file-ordered group.

What refuses to combine:

Combination	Verdict
select/groupSelect + shuffle	rejected: select keeps the trial file order, which shuffle contradicts
select/groupSelect + sample/groupSample	rejected: one family per group
select/groupSelect + any constraint or structure word	rejected: it would reorder the file order the word promises
select/groupSelect + useOrder	rejected, by the rule that useOrder must stand alone in its group
select/groupSelect + saveOrder	allowed, except with groupSelect, which is a unit pick
shuffle + groupShuffle/shuffleWithin	rejected: different claims about the same order
shuffle + useOrder	rejected (useOrder must stand alone)
sample ...; shuffle	allowed, harmless redundancy
groupSample N col; shuffle	allowed: this is how you scatter the chosen units instead of keeping them whole
structure word + constraint	rejected: put them in separate groups
two groupSample (or two groupSelect, two first, two last)	rejected
groupSample + pattern, follows, notFollows, saveOrder	rejected
groupSample + a constraint on a DIFFERENT column	rejected
groupSample + a constraint on the SAME column	only maxRun and noRepeat are accepted; every other kind is refused, because which trials survive the pick is not known in advance
useOrder + anything else	rejected
saveOrder + groupSample/groupSelect	rejected: the surviving pool size is unpredictable
saveOrder + more than one sample/select	rejected when you save the file
two constraints on the same column, several select words in one group	allowed

Where a program is refused outright: a trialOrder group may not contain stimFormat = list rows (sample list items with listOptions instead) or rows with a staircase value; a colon in a randomBlock cell is not supported yet; and a file mixing block.-prefixed rules with trialOrder programs is rejected.

Defaults & missing values

• No trialOrder column, or every cell empty: nothing moves. Every trial runs in the order it is written in the file.
• An empty cell, or 0: the row takes part in no group, keeps its file position and closes the group above it. A cell of nothing but zeros (00) counts as 0.
• An empty cell in a column a program names is unconstrained filler. It breaks up maxRun runs, is skipped by alternate, gap and balance, forms its own unit for groupShuffle and its own stratum for shuffleWithin, and is always kept by sample N col and by groupSample. No value written into a program can ever match it.
• Group numbers are not defaults: there is no implicit program. A group of bare numbers is an error, not a shuffle.
• repeat weights count. A row counts toward its pool as many times as its repeat value says; an empty repeat cell counts once, and 0 counts not at all.
• The program text is not part of your data. Once the file is saved, every row of the group holds the bare group number, and that is also the value the results file records.

Works with

• When it happens: selection and ordering run after the subjectGroup filter, so every pool draws from the trials this participant actually receives. If a program cannot be satisfied, the participant gets This experiment cannot start: <message> instead of a mis-sampled design.
• Pools split at randomBlock, type and timer boundaries. A group that spans several block values, trial types or timer sections applies its whole program inside each part separately. Trials sharing a timer label count as one section, so t1: 30 and t1: 60 stay in the same pool.
• randomBlock: plain block numbers combine freely, and the between-block shuffle still runs before your program, so blocks may swap order as wholes while each block’s trials are selected and ordered on their own. A colon in a randomBlock cell is rejected.
• type: a change of trial type ends a pool, so an instructions row inside a numbered group would fence it in two. In practice instruction screens are left blank, which takes them out of the group entirely.
• subjectGroup: selection runs after the filter, so the pool is the participant’s own rows. When you save the file it is checked against the combinations of subject groups a participant can be given, so a design that would only fail for some participants is caught before anyone runs it.
• repeat: repeated rows are expanded before the order is settled, so their weights count toward pool sizes and toward the size match between a saveOrder group and its useOrder group.
• random: the two columns cannot both be used. A random cell that carries a group value next to a trialOrder group is refused with the conversion: move random group 1 to trialOrder as "1: shuffle". A colon in a random cell is refused whatever the rest of the file does: the random column no longer takes specs (...); specs live in the trialOrder column now. The same refusal is repeated when the experiment is built, so a stale file that never went through the save-time check cannot run unsampled either, with one narrow exception for already-stored clock-like cells (see Tips & gotchas).
• randomPick / trialGroup: rejected alongside trialOrder, with the conversion named (express the sampling with sample / select / groupSample). Both are hidden from the editor’s add-column list.
• rules / block: block.sample / block.select rules run before your program and can shrink a pool below the size that was checked when you saved, so the combination is rejected.
• staircase, stimFormat = list: rejected inside a group that carries a program. Sample list items with listOptions instead.
• The saveOrder / useOrder bank: the bank lives for one run and groups are settled in file order, so an earlier group’s saved order is available to a later useOrder. What is banked is the order of the group’s SURVIVING trials, and replaying it puts the i-th trial of the replaying group where the i-th trial of the saved one ended up. A group that splits across a block, type or timer boundary can neither save nor replay: the group splits into 2 pools; keep the group within one randomBlock / type / timer span. Names are case-insensitive, each name is saved once, and a useOrder must name an order saved by an EARLIER group.
• Advanced randomisation (project setting): the selection draws (sample and groupSample picks) come from random.org when the setting is on; the ordering draws always use the built-in generator.
• Previewer: the previewer is lenient where a participant run is strict. Counts are capped instead of failing, an unsatisfiable constraint keeps the best order found, a useOrder with no saved order or the wrong size leaves the group alone, and bank words on a split group are ignored. A preview that looks fine is therefore not proof that a participant run will start.
• Results: selection only ever shrinks the presented list, and nothing is renumbered, so every trial that runs stays traceable to the trial-file row it came from.

What lands in the results file

• The realised order is the results file itself. Trial rows are written in presentation order and the first results column, rowNo, names the trial-file row each presented trial came from. Reading rowNo top to bottom recovers exactly the sequence the participant saw; dropped trials simply have no row. There is no separate trialOrder_actual field, and none is needed.
• The column itself round-trips. trialOrder travels to the results as a user-defined column, appended after the standard columns under its own name. The value recorded is the bare group number, never the program text.
• Downloads and exports show it; the in-app results views do not. The per-participant results CSV and the long-format export both carry trialOrder. The results views built on the queryable trial store show only the standard columns, which is equally true of the other recently added trial-file columns (stimOrder, stimScreens, stimList, stimOptions, trialGroup), so it is a property of those views rather than of trialOrder.

Examples

Shuffle three test trials and leave the instruction screen where it is (a blank cell takes the row out of the group):

type	stimFormat	stim1	title	content	button1	trialOrder
instructions			Welcome	You will see one word at a time.	NEXT
test	word	HOUSE				1: shuffle
test	word	TABLE				1
test	word	RIVER				1

Shuffle, but never show three trials of the same condition in a row:

type	stimFormat	stim1	condition1	keyboard	key	trialOrder
test	word	RED	congruent	r g b	r	1: shuffle; maxRun 2 condition1
test	word	GREEN	congruent	r g b	g	1
test	word	BLUE	incongruent	r g b	r	1
test	word	RED	incongruent	r g b	b	1

Keep at least 2 and at most 5 other trials between the two showings of an item (the numbers come first, and they count the trials BETWEEN the repeats):

type	stimFormat	stim1	itemId	keyboard	key	trialOrder
test	word	ANCHOR	i1	f j	f	1: shuffle; gap 2 5 itemId
test	word	BRIDGE	i2	f j	f	1
test	word	CANDLE	i3	f j	f	1
test	word	ANCHOR	i1	f j	j	1
test	word	BRIDGE	i2	f j	j	1
test	word	CANDLE	i3	f j	j	1

Show a random two of these three pictures, in the order they are written in the file (select keeps your order; sample would shuffle the two survivors):

type	stimFormat	stim1	presTime	keyboard	key	trialOrder
test	.png	cat_clear	800	f j	f	1: select 2
test	.png	dog_clear	800	f j	f	1
test	.png	bird_clear	800	f j	j	1

Give each participant one whole list, chosen at random, with the two lists staying intact:

type	stimFormat	stim1	listType	trialOrder
test	word	APPLE	semantic	1: groupSample 1 listType
test	word	PEACH	semantic	1
test	word	TABLE	phonological	1
test	word	STABLE	phonological	1

Study a list in a random order, then test the same items in the same order (the instruction screen between them closes the first group and opens the second):

type	stimFormat	stim1	itemId	title	content	button1	trialOrder
test	word	ANCHOR	i1				1: shuffle; saveOrder studyList
test	word	BRIDGE	i2				1
test	word	CANDLE	i3				1
instructions				Test phase	Now judge each word you saw.	NEXT
test	word	ANCHOR	i1				2: useOrder studyList
test	word	BRIDGE	i2				2
test	word	CANDLE	i3				2

Tips & gotchas

Caution

Leave the random column out of a trialOrder file, or blank it. A random column full of 0s is accepted next to trialOrder, but 0 is not an empty cell: it opens one big legacy shuffle run before your program is ever applied.

• A group is a contiguous run, and the number is not a link. Group 1 used in two stretches separated by a row that takes part in no group is two independent groups, each needing its own program. Repeating the identical program text on several rows of one group is tolerated; different text is a conflict error.
• 0 is not a group number. A bare 0 means “this row stays put”; 0: shuffle is rejected rather than treated as group zero.
• Adding a constraint to a groupSample group changes the presentation. 1: groupSample 1 listType keeps each chosen unit whole and puts the units in a random order, but as soon as the group also carries a constraint the surviving trials are reordered from a full shuffle. Write groupSample N col; shuffle when you want the units scattered on purpose.
• Structure words are defined against the trial FILE order. groupShuffle and shuffleWithin restore the file order of the pool before they run, so an earlier block shuffle does not leak into their result. groupShuffle gathers scattered rows of one value into a single unit, in first-appearance order.
• first/last without a randomising word are deterministic. They pull the first (last) matching trials to the edge and leave everything else in file order, which is a pin, not a shuffle.
• alternate needs values that are equally often present (counts may differ by at most 1) and at least two distinct values, or the file is rejected when you save it.
• balance N col needs the arithmetic to work out: each value’s count times the window size must divide the pool size evenly, otherwise no arrangement can hold a whole number of that value per window.
• A crossed value is filler as soon as one half is missing. A trial with an empty cell in either column of a difficulty*intensity crossing counts as unconstrained filler, not as a cell of the design.
• Save-time checks read one word at a time. They never accept a provably impossible program, but two words that are impossible only in combination can pass the save and fail during a run instead; pattern is the one word whose check is exact in both directions.
• The search for a valid order eventually gives up. A participant run halts with could not find a trial order satisfying <spec> after 200 attempts; the previewer silently keeps the closest order it found.
• One narrow leniency for old files. A clock-like value such as 12:30 or 1:30 min stored in the random column before this rule existed keeps running; re-saving that file rejects it.

Common combinations

trialOrder appears in these worked recipes:

• Replayed random order: Shuffle a block once, then replay that exact order in a later block so both passes share identical order effects.
• Self-paced reading: Present sentences one segment at a time, advanced by the space bar, with a reading time recorded per segment and sentences shuffled as whole units.
• Balanced condition windows: Shuffle trials while keeping the conditions evenly distributed across the whole session, so neither condition clusters early or late.
• Constrained condition order: Shuffle trials while guaranteeing the same condition never runs more than twice in a row.
• Sample per condition: Show each participant a fixed number of trials per difficulty level, drawn fresh from a larger pool every session.