label

Experiments Surveys & forms On JSON-form projects the results reuse the label column for each question's name, replacing the row's own label.

label gives a trial row a stable name so other columns can point at it without hard-coding row numbers: as a then jump target, inside %var[label]% variable references (in if conditions, feedback and trial text), as a background-audio stop marker, and as human-readable progress info in attrition events. Prefer labels over numeric row targets whenever rows may be inserted or reordered later.

Syntax

Type a name into the label cell of the row you want to point at, for example practice_start. Other columns can then refer to that row by name instead of by row number.

The value is free text, but stick to letters, digits and underscores and start with a letter: the columns that read labels accept slightly different character sets (see Options).

Options

There are no keywords; the value is free text, but the practical character set is constrained by the consumers:

Consumer	Accepted label characters	Code
then destination	any exact text, matched only after then has ruled out row numbers, end, screenout, timer actions and URLs
%response[label]% in if conditions	starts with a letter or underscore, then letters, digits and underscores
%response[label]% in trial text and feedback	letters, digits and underscores (case-insensitive), plus ,/_ as list/range separators
background audio stop condition	the label text, with surrounding spaces trimmed

Recommendation derived from the above: use letters, digits and underscores, starting with a letter, and avoid purely numeric labels (see Tips & gotchas). Avoid underscores in labels meant to bound a [from_to] range, because the range is split on every _ (see Works with).

Defaults & missing values

Leaving the cell empty means the row has no name. It can still be reached by its row number, just not by label, and the column can be left out of the file entirely.

If two rows carry the same label, only the first of them wins: later rows with that label cannot be reached by name at all.

Works with

• then: then="my_label" jumps to the labeled row. If the label exists but that row is not part of this participant’s trial order, the experiment ends; an unknown label is ignored and the flow simply continues.
• if, feedback and trial text variables: %response[my_label]%, %rt[my_label]% and %correct[my_label]% give you the value recorded on the labeled row. Labels can also bound a range, for example %correct.sum[blockstart_blockend]%, with the aggregate written before the bracket.

Caution

Labels used as range bounds must not contain underscores, because the range is split on every _. [first_last] works; a range between labels called block_start and block_end does not.

• Background audio: a stop condition naming a label stops looped background audio at that row.
• Drop-out tracking: when the current row has a label, it travels with the experiment’s progress events, so you can see how far participants got in readable terms instead of as row numbers.
• JSON form projects: on those trials the results reuse the label column for each question’s name, one result row per question, so the label you gave the trial does not appear in the output.

Examples

Jump back to a labeled practice block until performance is good enough:

type	stimFormat	stim1	key	label	if	then
practice	.png	p1	1	practice_start
practice	.png	p2	2		%correct.perc%>=80;%correct.perc%<80	main_start;practice_start
test	.png	t1	1	main_start

Show an earlier answer in trial text via a label reference:

type	trialText	keyboard	label
test	What is your favourite color?	red green blue	color_q
test	You said %response[color_q]%. Press space.	space

Tips & gotchas

Caution

Never use a purely numeric label. A numeric then destination is read as a trial-file row number, so a row labeled 12 can never be jumped to by name.

• A misspelled label behaves exactly like no jump at all: the participant continues with the next trial and nothing warns you.
• A label can never look like a web address, because then treats anything starting with http:// or https:// as a redirect.
• The label column is saved into the results like any other column, except on JSON form trials, where it holds question names instead.

Common combinations

label appears in these worked recipes:

• Skip on response: Ask one question and jump participants who answer yes straight past the practice block.
• Accuracy-gated progression: Let participants advance to the test block only once their practice accuracy clears a threshold.
• Branching questionnaire: Route participants to different questionnaire pages depending on their answer to an earlier question.