Nested block shuffle

Randomise the order of whole task sections and of the mini-blocks inside each section, keeping every block’s trials together.

When to use it

Use this when the session is organised as sections containing mini-blocks, and both levels of order should vary across participants: which section comes first, and how the mini-blocks are arranged inside it. Counterbalancing this by hand means one trial file per permutation, which multiplies fast and splits your sample thin. A single randomBlock column with two-level identifiers does it in one file. If only the trials themselves should mix, with no block structure to preserve, a plain random run is all you need.

Trial file

type	content	stimFormat	stim1	randomBlock	keyboard	key	button1
instructions	Press A if the word names an animal and L if it does not.						NEXT
test		word	HORSE	1 1	a l	a
test		word	SPOON	1 1	a l	l
test		word	TIGER	1 2	a l	a
test		word	CHAIR	1 2	a l	l
test		word	CAMEL	2 1	a l	a
test		word	BOTTLE	2 1	a l	l
test		word	SHEEP	2 2	a l	a
test		word	PENCIL	2 2	a l	l

type,content,stimFormat,stim1,randomBlock,keyboard,key,button1
instructions,Press A if the word names an animal and L if it does not.,,,,,,NEXT
test,,word,HORSE,1 1,a l,a,
test,,word,SPOON,1 1,a l,l,
test,,word,TIGER,1 2,a l,a,
test,,word,CHAIR,1 2,a l,l,
test,,word,CAMEL,2 1,a l,a,
test,,word,BOTTLE,2 1,a l,l,
test,,word,SHEEP,2 2,a l,a,
test,,word,PENCIL,2 2,a l,l,

How it works

Every test row carries a two-level randomBlock identifier, space-separated with the leftmost level outermost: 1 1 means sub-block 1 of section 1. Consecutive rows sharing a value form one block. At the outer level, sections 1 and 2 swap order as wholes; at the inner level, each section’s two sub-blocks shuffle among themselves, because inner blocks only shuffle among blocks that share the same outer identifier. Trials inside each sub-block keep their file order, since no random column is present. Block randomisation is automatic the moment the column holds any value; there is no separate switch.

The instructions row leaves its randomBlock cell empty, which anchors it in place and makes it a fixed separator. Because it sits before all four blocks, the whole block structure shuffles freely behind it. Position matters here: an empty cell (or a 0) between two sections splits the segments at every level, so a break screen placed between sections 1 and 2 would stop the two sections from swapping. Keep such rows out of the middle unless pinning the section order is exactly what you want.

Stick to numeric identifiers. Letter identifiers still split blocks on value changes, but the fixed-separator behaviour of empty cells and 0 breaks down next to them, and some labels get silently corrupted. Also make each block one contiguous run: rows with the same identifier separated by other rows count as separate blocks. Sampling specs are not allowed in randomBlock cells; those belong in trialOrder.

Variations

Shuffle the trials inside each sub-block too: put the run tag 1 in random on every test row. The full randomBlock value bounds each run, so trials mix within their sub-block first, then the blocks shuffle as units.
Pin the section order but keep the inner shuffles: insert a break screen with an empty randomBlock cell between the two sections; the empty cell splits every level’s segments.
Drop to a single level by writing plain 1 and 2 in randomBlock for straightforward block-order shuffling.
Do not go deeper: identifiers with three or more levels in randomBlock do not shuffle correctly. Two levels is the maximum.