rules

Experiments Surveys & forms

rules holds block-selection expressions that run once at experiment start and rewrite the initial trial order: randomly keep a subset of the blocks defined by the block column, optionally shuffling the kept blocks’ order. Use it for “show each participant k of N counterbalanced blocks” designs. Exactly two expressions are recognized: block.sample(...) and block.select(...). Anything else is silently ignored.

Syntax

Put a single expression in one cell, for example block.sample(A, B, C, 2) to keep 2 of the blocks A, B, C in random order.

block.sample(<blockId>, <blockId>[, <blockId>...], <count>)
block.select(<blockId>, <blockId>[, <blockId>...], <count>)

• List at least one block identifier, then the count as the final argument.
• Identifiers may contain letters, digits and underscores only; spaces around the commas are fine.
• The count must be a plain whole number (no sign, no decimals).
• The cell may sit on any row; a rule applies to the whole experiment, not just its own row. Every non-empty rules cell is collected in row order and applied in that order.

Options

Expression	Effect
block.sample(b1,...,bN, k)	Randomly pick k distinct entries from the listed identifiers without replacement. Trials of listed-but-unpicked blocks are removed; the picked blocks are re-inserted, in the random order they were sampled, into the position slots the picked blocks occupied; trials whose block value is not listed are untouched. Net effect: keep k of the listed blocks AND shuffle their relative order.
block.select(b1,...,bN, k)	Randomly pick k of the listed identifiers, keep their trials in the original file order, and remove trials of the other listed blocks; unlisted trials untouched. Net effect: keep k of the listed blocks WITHOUT reordering.
anything else	Silently ignored; the trial order is left unchanged.

Defaults & missing values

If the column is absent, or every rules cell is left blank, the trial order is simply left as-is. Empty and whitespace-only cells are skipped; only cells containing an expression have any effect.

Works with

• block: supplies the identifiers a rule refers to; matching against each trial’s block value is exact and case-sensitive.
• Ordering: rules run on the initial file order, before random/randomBlock shuffling and before randomPick. The kept trials then go through the normal randomization.
• repeat / wildcards: rules are collected after rows are expanded, so a rule sitting on a row with repeat=3 is collected and executed 3 times (see Tips & gotchas).
• Results: the rules cell value is written into the raw results CSV like any other recognized column.

Examples

Show 2 of 3 blocks in random order:

type	stimFormat	block	rules	stim1	presTime
test	.jpg	A	block.sample(A, B, C, 2)	a1	1000
test	.jpg	A		a2	1000
test	.jpg	B		b1	1000
test	.jpg	B		b2	1000
test	.jpg	C		c1	1000
test	.jpg	C		c2	1000

Result: exactly two of A/B/C survive, their block order is random, each block’s internal trial order is preserved (until random/randomBlock apply).

Show 1 of 2 blocks, keeping file order (no shuffle):

type	stimFormat	block	rules	stim1
test	.jpg	version1	block.select(version1, version2, 1)	v1_1
test	.jpg	version1		v1_2
test	.jpg	version2		v2_1
test	.jpg	version2		v2_2

Tips & gotchas

• All failure modes are silent: a bad function name, a malformed argument list, an identifier with characters other than letters, digits or underscores, or a count with a sign or decimal point all make the rule do nothing, with no warning.
• If one cell somehow contains both a block.sample(...) and a block.select(...) expression, only the block.select one applies.
• A count larger than the number of listed identifiers behaves the same as a count equal to the number listed: every listed block is kept (and block.sample still shuffles their order).

Caution

With block.sample, a listed identifier that matches no trial’s block value (a typo, a case mismatch, or a name that exists only in the rule) can break the experiment at startup, or can silently leave fewer blocks than the count. block.select tolerates absent identifiers. Double-check every identifier in the rule against the block column.

• Do not list the same identifier twice: a duplicate can be picked twice, wasting a pick, and you end up with fewer distinct blocks than the count.

Caution

A rule on a row that gets duplicated (a repeat value, or list expansion) executes once per copy. Repeated block.select runs drop further listed blocks from the survivors of earlier runs (usually ending with far fewer blocks than intended), and repeated block.sample runs reshuffle and remove again. Put the rule on a row with no repeat value and no list expansion.

• There is no pick:2 syntax; the two block.* forms above are the only ones.

Common combinations

rules appears in these worked recipes:

• Pick a subset of blocks: Give each participant a random two of three self-contained tasks, each opening with its own instructions screen.