Skip to content

Choice Response

A choice response allows participants to choose between several alternatives.

Required Properties

type

  • Definition: The type of response.
  • Possible values: For a choice response, "type" must be specified as "choice".
  • See also: choices
1
2
3
4
{
  "type": "choice",
  "choices": ["optionA", "optionB"]
}

choices

  • Definition: A list of options, including target values and any alternatives.

  • Possible values: Plain text labels (e.g., "optionA") or the names of a defined image, video, or text stimulus, in a special format ("%s:name-of-stimulus"). Plain text labels and stimulus references can be mixed, but in some cases, it doesn't make sense to do so (e.g., mixing labels and videos).

    Using Image or Video Stimuli as Choices

    If the options specified are plain text labels, they will be displayed as clickable buttons during the study.

    Alternatively, if stimulus names are used (in the special format mentioned above), FindingFive will render the corresponding stimulus. For example:

    • A clickable image will be rendered if the referenced stimulus is an image.
    • A clickable video will be rendered if the referenced stimulus is a video.
    • A clickable text box will be rendered if the referenced stimulus is a text stimulus.

    Most choice response properties are supported for both plain text labels and stimulus references. However, there is an exception: the multi_select property currently works only with plain text labels.

Example using plain text labels

1
2
3
4
{
  "type": "choice",
  "choices": ["optionA", "optionB"]
}

Example using stimulus references

1
2
3
4
{
  "type": "choice",
  "choices": ["%s:stimulus1", "%s:stimulus2"]
}

Optional Properties

duration_timer

  • Definition: Whether to show a duration timer that indicates the time elapsed since the reponse becomes visible.
  • Possible values: true,false
  • Default: false
1
2
3
4
5
{
  "type": "choice",
  "choices": ["optionA","optionB"],
  "duration_timer": true
}

duration_timer_onset

Dependencies

Requires duration_timer to be set to "true".

  • Definition: When to show the duration timer. When set to "start", the timer will appear as soon as the response is displayed and animate a stopwatch effect. When set to "end", the duration timer will only appear once the participant has made a reponse with no stopwatch effect.
  • Possible values: "start", "end"
  • Default: start
1
2
3
4
5
6
{
  "type": "choice",
  "choices": ["optionA","optionB"],
  "duration_timer": true,
  "duration_timer_onset": "start"
}

feedback

Dependencies

Requires target to be defined.

  • Definition: Whether or not participants will receive feedback on their response. If the option selected matches the "target", participants will be informed that their response is correct ("Your response is correct!"), and they will hear a “ding!” bell sound. If the option selected does not match the "target", participants will be informed of the correct response ("Sorry! The correct answer is highlighted in green."), and they will hear a “buzz” sound.
  • Possible values: true,false
  • Default: false
1
2
3
4
5
6
{
  "type": "choice",
  "choices": ["optionA", "optionB", "optionC"],
  "target": "optionC",
  "feedback": true
}

feedback_audio

Dependencies

Requires target to be defined and feedback to be set to true.

  • Definition: If "target" is defined and "feedback" is set to true, by default, participants will receive auditory feedback on their responses (a “ding!” bell sound for correct responses and a “buzz” sound for incorrect responses). Setting "feedback_audio" to false disables these sounds.
  • Possible values: true,false
  • Default: true
1
2
3
4
5
6
7
{
  "type": "choice",
  "choices": ["optionA", "optionB", "optionC"],
  "target": "optionC",
  "feedback": true,
  "feedback_audio": false
}

font_size

  • Definition: The font size of the text in choice response options
  • Possible values: Either 1) HTML font sizes such as "px", "em", or "rem", or 2) a percentage of the default size
  • Note: The rendered outcome might differ across browsers and devices.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "type": "choice",
  "choices": [
    "LEFT",
    "RIGHT"
  ],
  "font_size": "25px",
  "target": "LEFT",
  "instruction": "Choose wisely, Indiana Jones!"
}

hint

Dependencies

Requires key_mapping to be defined.

  • Definition: Whether or not participants will see a text hint about which keys can be pressed to select the corresponding choice option. When set to false, the text will not be visible (which may potentially cause confusion for participants as to how to continue the study if key_only is set to true).
  • Possible Values: true, false
  • Default: true
1
2
3
4
5
6
7
{
  "type": "choice",
  "choices": ["optionA", "optionB"],
  "key_mapping": ["F","J"],
  "key_only": true,
  "hint": true
}

incremental_feedback

Dependencies

Requires multi_select to be true and target to be defined.

  • Definition: Whether or not participants will receive immediate feedback after each selection they make. This applies only to questions in which more than one option may be selected.
  • Possible values: true,false
  • Default: false
1
2
3
4
5
6
7
{
  "type": "choice",
  "choices": ["optionA", "optionB", "optionC"],
  "multi_select": true,
  "incremental_feedback": true,
  "target": ["optionA", "optionB"]
}

  • This can be turned on or off independently of feedback.

    For example, if "feedback" is true and "incremental_feedback" is false, then participants will only receive feedback after they confirm their selections. If "incremental_feedback" is true and "feedback" is false, then participants will receive feedback after each selection, but not once they confirm all of their selections.

instruction

  • Definition: A short text providing the necessary instructions for participants about the current response. Use empty quotes ("") to remove the instruction text.
  • Possible values: Any string
  • Default: "Click the answer that you think is most likely correct."
1
2
3
4
5
{
  "type": "choice",
  "choices": ["optionA", "optionB", "optionC"],
  "instruction": "The text in these quotation marks will be displayed."
}

key_mapping

  • Definition: A list of single-character individual key names (e.g., ["F", "J"]), specifying which key can be pressed to choose the option presented.
  • Possible values: Any alphanumeric key (A-Z, 0-9)

Note

The length of this list must be the same as the number of choices.

What if the locations of the choices are randomized?

If locations is set to "random" to randomize the presentation order of the choices, key mappings will not be randomly assigned alongside the options. Instead, keys will be mapped to options based on their positions from left to right. For example:

  • The first key (e.g., "F") will correspond to the option randomly assigned to appear on the left.
  • The second key (e.g., "J") will correspond to the option randomly assigned to appear to the right of the first, and so on.

In summary, the correspondence between options and keys is location-aligned—keys are tied to specific locations rather than to particular options.

1
2
3
4
5
{
  "type": "choice",
  "choices": ["optionA", "optionB"],
  "key_mapping": ["F", "J"]
}
In this example, because "locations" is left at its default setting, optionA will appear on the left, with the instruction to press F, and optionB will appear on the right, with the instruction to press J. However, if "locations" were set to random, F would always be associated with the option on the left, and J with the option on the right, but the locations of optionA and optionB would be randomized.

key_only

Dependencies

Requires key_mapping to be defined.

  • Definition: If "key_mapping" is defined, setting this property to true will allow participants to respond with key presses only.
  • Possible values: true,false
  • Default: false
1
2
3
4
5
6
{
  "type": "choice",
  "choices": ["optionA", "optionB"],
  "key_mapping": ["F", "J"],
  "key_only": true
}

layout

  • Definition: This property specifies the layout of options listed in "choices". Options may be displayed in multiple rows if desired.

  • Possible values:

    • List of two integers in the format [M, N], where M is the number of rows and N is the number of options per row (e.g. [2,2], corresponding to options displayed in 2 rows, with 2 options per row).

    Note

    The product of M and N must be equal to the total number of options specified as choices. For example, when there are 4 options, [1, 4], [2, 2], and [4, 1] are valid layout options.

    • Two text shortcuts "horizontal" and "vertical" are also available, standing for [1, N] and [M, 1], respectively. That is, setting "layout" to "horizontal" places all options in one row, while setting "layout" to "vertical" places all options in one column.

  • Default: All options are presented in a single row [1, N], where N is the number of options defined in choices (equivalent to text shortcut "horizontal")

1
2
3
4
5
{
  "type": "choice",
  "choices": ["optionA", "optionB", "optionC", "optionD"],
  "layout": [2, 2]
}
In this example code, "optionA" and "optionB" appear in one row, and "optionC" and "optionD" in another.

locations

  • Definition: Whether the locations of the options are randomly determined on a trial.
  • Possible values: "fixed" or "random"
  • Default: "fixed"
  • If set to "fixed" (or by default), options will be displayed in the order in which they are listed in "choices"
1
2
3
4
5
{
  "type": "choice",
  "choices": ["optionA", "optionB", "optionC", "optionD"],
  "locations": "random"
}

mode

  • Definition: The display mode for the choice options. By default (i.e., not specifying the mode explicitly), each choice is displayed as a button. The alternative is to display the options as a dropdown (important: see the warning message below).

  • Possible values: "button","dropdown"

    Dropdown does not work with multi-selection

    Setting both multi_select to true and mode to "dropdown" will crash an experiment. We are working on supporting this feature in the next study grammar update.

  • Default: "button"

1
2
3
4
5
{
  "type": "choice",
  "choices": ["optionA", "optionB", "optionC", "optionD"],
  "mode": "dropdown"
}

multi_select

Warning

Multi-selection currently only works with plain text labels, not with clickable stimuli (see here).

  • Definition: Whether participants are or are not allowed to select more than one option as defined in "choices". Participants will be prompted to confirm their responses (via a "Confirm" button) before submitting them.
  • Possible values: true,false
  • Default: false
1
2
3
4
5
{
  "type": "choice",
  "choices": ["optionA", "optionB", "optionC", "optionD"],
  "multi_select": true
}

ordered

Dependencies

Requires target to be defined and multi_select to be set to true.

  • Definition: Whether or not options must be selected in the order specified in "target" to be considered correct.
  • Possible values: true, false
  • Default: false
  • When set to true, a participant's response will be considered incorrect even when the correct set of options are selected, but in an order that does not match the order specified in"target".

1
2
3
4
5
6
7
{
  "type": "choice",
  "choices": ["optionA", "optionB", "optionC", "optionD", "optionE", "optionF"],
  "target": ["optionC", "optionE"],
  "multi_select": true,
  "ordered": true
}
In this example, if participants select optionC first and optionE second, then their response will be marked as correct. However, if participants select optionE first and optionC second, then their response will be marked as incorrect.

parent

  • Definition: If specified, then the properties of the other response will be inherited by this response, unless a property of the same name is defined in this response.
  • Possible values: The name of another defined response

Given a response named "choices1" that is defined as follows:

1
2
3
4
5
{
  "type": "choice",
  "choices": ["optionA", "optionB", "optionC"],
  "instruction": "Please indicate which of the following options you find most appealing"
}

We can define a second response called "choices2" that inherits the instruction of "choices1" but has it own set of choices:

1
2
3
4
5
{
  "type": "choice",
  "choices": ["optionD", "optionE", "optionF"],
  "parent": "choices1"
}

record_location

  • Definition: Whether or not to include the location of the response option selected by the participant in the result CSV. This feature is most useful when locations is set to "random".
  • Possible values: true, false
  • Default: "false"
  • Note: The location of the selected response option will be provided in the form of the nth option shown in the response (ordering from left to right, top to bottom). For example, a value of 1 means the first option is selected, a value of 2 means the second, and so on. This value will be included with the "response_mode" column in the CSV.

1
2
3
4
5
{
  "type": "choice",
  "choices": ["optionA", "optionB", "optionC", "optionD", "optionE", "optionF"],
  "record_location": true
}
In this example, the results CSV will include the location of the choice selected by the participant within the "response_mode" column. For example, if the participant selects optionA, the "response_mode" column will include "1", representing the first choice location (or "2" for optionB, "3" for optionC, etc.).

Note that this is most useful if locations is set to "random", as the locations of the choices can not be determined based on their ordering in the response definition.

sample_k

  • Definition: Instead of presenting all of the options defined in choices, sample k out of them randomly. If "target" is defined, those options will always be presented and count towards k. The number of options not specified as targets that are displayed will be equal to k - the number of defined targets.
  • Possible values: an integer no greater than the total number of options as defined in "choices"
  • Default: total number of options as defined in "choices"

1
2
3
4
5
6
{
  "type": "choice",
  "choices": ["optionA", "optionB", "optionC"],
  "target": "optionC",
  "sample_k": 2
}
Here, optionA will be automatically displayed because it is defined as a "target". In addition, one (k - 1) of the remaining options (optionB or optionC, determined at random) will be presented.

target

  • Definition: A single correct answer, or a list of correct answers. All target values must already be listed in "choices".
  • Possible values: Single plain text label (e.g., ["correct"]) or stimulus reference (e.g., ["%s:stimulus1"]). Also supported: lists of plain text labels (e.g., ["correct", "also correct"]) or stimulus references (e.g., ["%s:stimulus1", "%s:stimulus2"].
  • When target is a list, participants’ choices must exactly match all listed targets.
1
2
3
4
5
{
  "type": "choice",
  "choices": ["optionA", "optionB", "optionC"],
  "target": "optionC"
}

target_match

Dependencies

Requires target to be defined.

  • Definition: If set to true, participants must select an answer that matches the "target" as defined above in order to continue the study.
  • Possible values: true,false
  • Default: false
1
2
3
4
5
6
{
  "type": "choice",
  "choices": ["optionA", "optionB", "optionC"],
  "target": "optionC",
  "target_match": true
}

timeout

  • Definition: The length of time, in seconds, that a choice response will accept a participant response. After this time has passed, the choice response will grey out and a null participant response will be recorded. If "feedback" is set to true, then feedback will be given.
  • Possible values: A number of seconds, decimals supported (i.e., 1.5)
  • Default: 0, meaning that the choice response stays active indefinitely until a participant response is received.
1
2
3
4
5
{
  "type": "choice",
  "choices": ["optionA", "optionB", "optionC"],
  "timeout": 5
}

wrap

  • Definition: Whether to wrap the choice options if there are too many to fit in a single row.
  • Possible values: true,false
  • Default: false
1
2
3
4
5
{
  "type": "choice",
  "choices": ["optionA", "optionB", "optionC"],
  "wrap": true
}

Recorded Data

  • value: the choice made by the participant
  • correct: whether the choice(s) made by the participant matches "target"
  • rt: reaction time, defined as the number of milliseconds between the start of the presentation of the buttons and the moment when the participant makes a choice
  • mode: whether the participant responded via a key press or a mouse click