stimOrder

Experiments

stimOrder constrains how a trial’s stimuli are randomised: instead of the unconstrained shuffle of stimOptions random, a random(...) spec keeps chosen structure intact while everything else shuffles. The column answers one question: which arrangement of this trial’s stimuli does the participant see. Use it when a design needs pairs that travel together (chunk), shuffling confined inside units or screens (within, within screens), whole screens reordered (screens), or specific stimuli pinned to exact, bounded or relative positions while the rest shuffle around them (pin, dot-probe or attentional-blink style).

The column is spec-only: a cell is exactly one random(...) group, or empty. The legacy unconstrained shuffle stays where it always was, the bare random keyword in stimOptions; writing bare random here is a validation error with a pointer back.

Syntax

The whole cell is one random(...) group. Keywords are case-insensitive and whitespace inside the parentheses is free:

• random(chunk 2) / random(chunk 2+3+2) — consecutive units shuffle as wholes, within-unit order preserved. A uniform size must divide the stimulus count evenly; explicit sizes must sum to it (the counts grammar is the same as stimScreens).
• random(within 2) / random(within 2+3+2) — shuffle inside each unit, unit order fixed.
• random(screens) / random(within screens) — units come from the row’s stimScreens cell: whole screens shuffle, or stimuli shuffle within each screen (screen composition fixed). Both forms require a stimScreens value on the row.
• random(pin <refs>) / random(pin <refs>; segments) — pinned stimuli are placed first, the rest shuffle across the free positions as one pool, or per-segment between the pins with segments. Each ref is a 1-based authored position or a unique (non-numeric) stimulus name, optionally placed with @: exact @5, ranges @2_6, @2_, @_6, or relative to the previously placed pin @+2, @+2_6, @+2_. The first pin may not be relative.

random(sample ...) is rejected as “not supported yet” (it would change the stimulus count).

Options

Value	Effect
empty cell	No constrained ordering; the row keeps its authored order (or the legacy stimOptions random shuffle if that keyword is present)
random(chunk N) / random(chunk a+b+c)	Consecutive units shuffle as wholes, inner order preserved
random(within N) / random(within a+b+c)	Shuffle inside each unit, unit order fixed
random(screens)	The row’s stimScreens screens shuffle as wholes
random(within screens)	Stimuli shuffle within each stimScreens screen
random(pin refs)	Pinned stimuli placed per their @ placements; the rest shuffle as one pool across the pins
random(pin refs; segments)	As above, but pins act as barriers: each stretch of unpinned stimuli shuffles only within itself
anything else	Validation error; the column is spec-only (bare random gets a pointer to stimOptions)

Defaults & missing values

With the column absent or the cell left empty, nothing changes: the row keeps its authored order. There are no defaults to fill; a spec either resolves or the trial does not run (see the halt behavior under Works with).

The cell value is echoed into the results file like any other column, so the results show the spec each trial ran under, next to the resolved order in stimOrder_actual.

Works with

• One draw per session: each spec trial’s arrangement is drawn once when the experiment starts and repeats at every display of that trial in the session, unlike the bare stimOptions random keyword, which reshuffles every time.
• Impossible versus unlucky placements: a placement that could NEVER work (a pin range entirely outside the stimulus positions, two pins forced onto the same position, a chained offset that runs past the end) is rejected when the file is saved. A placement that is possible but happens to draw badly retries; if a participant run still cannot satisfy it, the experiment stops with an error page rather than running a wrong design. The previewer never stops, so a design that only ever fails for participants is caught by the save-time check, not the preview.
• Results: the resolved arrangement is recorded in stimOrder_actual, so the data shows exactly what each participant saw — including where a pinned target actually landed.
• key scoring: with a stim-referencing key, the correct stimulus is tracked through the reorder, so scoring follows the content, not the slot. Click responses stay attached to the right stimulus the same way.
• stimScreens: both screens forms use the row’s screens and require a stimScreens cell. chunk/within units are independent of screens and may cross screen boundaries.
• stimOptions boundary: the two columns cannot both randomise one row — a spec next to the bare random keyword is a validation error, and a random(...) group written into stimOptions errors with a pointer here. Settings (playback flags, CSS blocks) combine freely with a spec.
• Where specs do not apply: instruction and form rows, audio/video rows (those always play sequentially), rows with a target (list every stimulus in stim instead), and list-driven rows whose stimulus count is only known at run time.
• Old experiment links: an experiment built before this column existed simply ignores it, so spec trials show their authored order there instead of applying a misleading free shuffle.

Examples

Dot-probe with a floating target: the probe pair shuffles, the dot lands anywhere in positions 3-5 and its partner exactly 2 later:

type	stim	stimOrder	presTime	ISI	keyboard	key
test	w1;w2;XX;w3;w4;YY;w5;w6	random(pin 3@3_5 6@+2)	400*8	0*7	f j	j

Paired stimuli that travel together, pair order random:

type	stim	stimScreens	stimOrder	presTime	ISI
test	A1;A2;B1;B2;C1;C2	2	random(chunk 2)	800;800	300;300

Left/right position shuffles within each screen, screen composition fixed:

type	stim	stimScreens	stimOrder	presTime	ISI	keyboard	key
test	P1;P2;Q1;Q2	2+2	random(within screens)	900	400	f j	f

Tips & gotchas

Note

A spec trial repeats its resolved order within a session; across participants the orders differ. stimOrder_actual records exactly what each participant saw.

• The whole cell is ONE spec group: settings keywords around it (loop random(chunk 2)) or a second group are errors, not merged; playback settings belong in stimOptions on the same row.
• Range placements may extend beyond the stream (@3_9 over 5 stimuli); they are clamped to the real positions when the order is drawn. Only ranges entirely outside the stream are errors.
• All-digit pin refs are always positions, never names; a stimulus literally named 12 must be pinned by its position.
• Name refs must match exactly one stimulus (case-insensitive); ambiguous names are errors with a pin-by-position hint.

Common combinations

stimOrder appears in these worked recipes:

• Counterbalanced sides: Show a fixed pair of stimuli with the left and right assignment drawn once per participant, and score the choice correctly whichever side the target lands on.
• Match to sample: Show a sample stimulus, then an array of choices in shuffled positions, scoring the matching choice correctly wherever it appears.
• Paired presentation: Present items in fixed pairs whose order shuffles for every participant while the members of each pair always stay together on screen.
• Attentional blink: Play a rapid serial stream with two embedded targets, then ask about both, with the second target’s report expected to suffer at short lags.