key

Experiments Surveys & forms In surveys, key scores a question's answer (per row on matrix questions); on experiment trials it defines the correct response.

key defines the correct answer / scoring rule for a trial. It is not a response-collection column; it never determines which keys can be pressed (that is keyboard). Whenever key is filled in, the trial’s response is scored against it and the result goes to the correct (or correctPractice) results column. It also drives correct/incorrect feedback branching, form-question scoring, sortable-trial scoring, and the “correct stimulus” concept for stimN values.

Syntax

Put the correct answer in the cell. On a keyboard trial that is the key you expect (a); on a typed or clicked trial it is the value you expect (cat). The trial is scored 1 in the correct results column when the response matches, and 0 when it does not.

Beyond a plain value, the cell accepts a small condition language:

• !value: correct when the response is anything other than value. Only numeric values negate reliably: !3 scores as written, !red does not (see Tips & gotchas).
• a|b (either) and a&b (both) combine sub-conditions.
• stimN, for example stim2: correct when the participant chose the stimulus in that slot.
• has(x) / !has(x): correct when the response does, or does not, contain x.
• <N, >N, <=N, >=N: numeric comparison against the response. If the value mentions RT, the comparison applies to the reaction time instead.
• A_B: correct when the response falls between A and B. RT300_800 applies the same range to the reaction time.
• responseCode=... / responseCode!=...: correct when the option codes recorded for the trial match the codes you list. Separate several codes with commas.
• correct / incorrect, %response%-style variables, participant details such as %id%, and [label] references are recognized as well.

Sort trials are scored differently: the cell lists the expected order of the sortable stimuli and the score is the summed positional distance from that order, not a simple correct/incorrect.

Note

Unlike if, the whole key cell is a single condition: a semicolon does not start a new one. On form and sort trials, semicolons separate the expected answers per row or per stimulus (see Options).

Caution

When a responseCode= key lists several codes, the order you write them in does not matter, but the codes recorded for the response must come out in ascending order for the match to succeed.

Options

Value form	Scored as
empty cell	Not scored; no correctness is recorded for the trial
word (plain value)	Response is exactly word
!word	Reliable only with a number: !3 is correct for any response other than 3. A non-numeric !word instead marks every response correct except 0 (see Tips & gotchas)
a|b, a&b	OR / AND combination of sub-conditions
stimN (e.g. stim2)	Correct if the participant chose stimulus N; still identifies the same stimulus when the display order is randomized
responseCode=2 or responseCode=1,3	Correct if the option codes recorded for the trial match the codes listed (their order in the cell does not matter, see Syntax)
responseCode!=2	Negated code match
has(x) / !has(x)	Response contains / does not contain x
<N, >N, <=N, >=N	Numeric comparison on response (on RT when RT appears in the value)
A_B / RTA_B	Range check on response / RT
0 (forms)	Correct means “nothing selected”
v1;v2;... (forms with response rows or several stimuli)	Per-row expected answers, ;-separated; _-separated groups per stimulus
stimA;stimB;... (sort trials)	Expected order of sortable stimuli; score is summed positional distance

Defaults & missing values

Leave the column out of the trial file, or leave a cell empty, and the trial is not scored: no correctness is recorded for it in the results, and correct/incorrect feedback cannot be shown for it.

On form questions, leaving key empty also keeps that question out of the average score reported at the end of the session.

Works with

• keyboard: keyboard responses are recorded as the key token (for example a or space), so put that same token in key to score them.
• feedback / feedbackCorrect / feedbackIncorrect: the correctness computed from key decides which feedback the participant sees.
• Randomized stimulus order: a stimN key follows the stimulus itself, so the trial is still scored against the intended stimulus after the display order has been shuffled.
• Forms: each question is scored with its own key. A plain-text key is compared with the answer text and a responseCode= key with the codes of the chosen options, on any question type. On option questions (radio buttons, dropdowns, ranking, checkboxes) a key of 0 additionally means “nothing selected is correct”. Questions with several rows, or one row per stimulus, produce a ;-separated correct string with one result per row, grouped with _ per stimulus, rather than a single correct/incorrect.
• type set to practice: correctness goes to the correctPractice results column instead of correct.
• if / then: they use the same condition language, but if splits on ; into several conditions while key does not.

Examples

type	stimFormat	stim1	keyboard	key
test	word	old_word	a l	a

Press A or L; A is scored correct (correct=1), L incorrect (correct=0).

type	stimFormat	stim1	stim2	stim3	stimOptions	key
test	.jpg	cat	dog	bird	random	stim2

Click-response trial; the stimulus loaded into slot 2 (dog) is correct even after display order is shuffled.

type	responseType	responseOptions	key
test	checkboxes	4;5;6;7	responseCode=2,4

Checkbox question; correct when options 2 and 4 (values 5 and 7) are selected. The key cell may list its codes in any order, but the match requires the codes recorded for the response to come out as 2;4, i.e. in ascending order (see Syntax).

Tips & gotchas

Caution

key is not an alternative spelling of keyboard. It never decides which keys can be pressed. A trial that only has key still collects clicks or typed input, and key merely scores whatever comes back.

Caution

Negation with ! only works when the value is a number. !3 scores as it reads: every response except 3 counts as correct. A non-numeric negation such as !red does not exclude red at all. It marks every response correct except the single response 0, red included, and nothing warns you, so the results come back with almost every trial scored correct. To score “anything but red”, list the answers that should count instead, for example blue|green.

• Matching is case-sensitive. With key set to A, a response of a is not scored correct, and the trial ends up with no correctness recorded at all rather than an incorrect. Write key in the same case as the responses you expect.
• responseCode= keys only make sense on trials that produce response codes, such as form questions and sliders. On other trials they never match.

Common combinations

key appears in these worked recipes:

• Click the target: Present several images as clickable response options and score the clicked target correctly even when display positions are shuffled.
• Type the answer: Collect a free-typed answer in an input box on a test trial and score it against the expected text.
• Adaptive staircase: Home in on a participant’s detection threshold by making trials harder after correct answers and easier after misses.
• Go/no-go task: Score a press as correct on go trials and a withheld response as correct on no-go trials.
• Nested block shuffle: Randomise the order of whole task sections and of the mini-blocks inside each section, keeping every block’s trials together.