block

Experiments Surveys & forms

block labels a contiguous run of trial rows as a named block so that a rules column expression (block.sample(...) or block.select(...)) can randomly keep and/or reorder whole blocks at experiment start. On its own the column does nothing; it only has an effect when a rules cell references its identifiers. It is unrelated to randomBlock (which drives block-order shuffling of the random system).

Syntax

Give every row of a block the same identifier; consecutive rows with the same value form one block:

block
A
A
A
B
B

Values are trimmed and matched exactly against the identifiers written inside the rule. Use only letters, digits, and underscores so the block can be referenced from a rule.

Options

Value	Meaning
any string, e.g. A, practice, 2	Block identifier for this row. Runs of equal values form one block. To be usable from a rule it must consist of letters, digits, and underscores only.
empty	Row belongs to no rule block. A trial whose block value is not listed in a rule is always kept in its original position.

There is no other parsing of this column.

Defaults & missing values

When the column is absent or a cell is left empty, that row belongs to no block: block rules never drop or move it. If rules is absent or contains no valid block.sample/block.select expression, the block column has no effect at all.

Works with

• rules: the only consumer of block. Block rules are applied once, at experiment start, to the trial list in file order.
• Block picking happens before random/randomBlock shuffling and before randomPick: the rule first keeps and orders whole blocks, then randomization applies to the surviving trials.
• Each identifier is expected to label one contiguous run of rows. If the same identifier reappears later in the file, the rule treats everything from its first to its last occurrence as one block, sweeping the unrelated rows in between along with it.
• repeat and list-wildcard expansion happen before blocks are identified, so a repeated row multiplies the trials inside its block.

Examples

Keep 1 of 3 counterbalanced blocks (see rules.md for the rule syntax):

type	stimFormat	block	rules	stim1	presTime
test	.jpg	A	block.select(A,B,C,1)	imgA1	1000
test	.jpg	A		imgA2	1000
test	.jpg	B		imgB1	1000
test	.jpg	B		imgB2	1000
test	.jpg	C		imgC1	1000
test	.jpg	C		imgC2	1000

Mixed labeled/unlabeled rows; the instruction trial is untouched by any rule:

type	stimFormat	block	stim1
instructions			welcome
test	.jpg	easy	e1
test	.jpg	easy	e2
test	.jpg	hard	h1
test	.jpg	hard	h2

Tips & gotchas

• block and rules values appear in the raw results download like other columns, but they are not imported into the results database.
• Identifier matching is case-sensitive: Block1 and block1 are different blocks.

Caution

Identifiers containing hyphens, dots, or spaces cannot be referenced from a rule; such blocks are silently unselectable. Stick to letters, digits, and underscores.

• Reusing an identifier in two separate, non-adjacent runs is not reported as an error; the rule simply treats the merged span from first to last occurrence as one block. Keep each block’s rows together.
• Only reference identifiers you actually wrote in the block column; do not try to target unlabeled rows from a rule. Unlabeled rows are meant to stay in place.

Common combinations

block 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.