Responses

Responses define the actions that participants can take in response to stimuli. They also implicitly specify what types of participant data will be recorded in a study.

A response is defined by a key-value pair inside the top-level property responses in a study runtime specification. Similar to a stimulus, the key of a response definition serves as the name of the response, which can be referenced in other parts of the specification. Its value specifies the type of the response, and its relevant properties.

For example, the following snippet

"response1": {
  "type": "choice",
  "choices": ["Correct", "Wrong"],
  "key_mapping": ["F", "J"],
  "target": "Correct", // or equivalently "target": ["Correct"]
  "feedback": false
}

defines a response of type choice, with two options labeled as “Correct” and “Wrong”. Each option will be rendered as a clickable button, and can also be triggered by pressing the F or J key respectively. Finally, the correct answer to this choice response is “Correct”, but no feedback will be given regardless of the participant’s choice.

Common properties

All responses share the following common properties:

  • type - must be specified as one of the types described below

  • parent (optional) - the name of another response; 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.

  • delay (optional) - delay the displaying of a response, relative to the latest onset of all stimuli on a given trial, by a certain number of seconds (fractions are supported). Default (or omission) is 0. This setting can be useful for forcing participants to read some text before making a response.

    Note

    The latest onset of all stimuli on a given trial is the moment when all stimuli just become visible (or start playing).

Visible responses

Visible responses can be seen by participants. They are usually used to explicitly elicit a response from participants.

choice

A choice response allows participants to choose between several alternatives.

Properties:
  • type - must be specified as choice
  • choices - a list of options in the form of ["option1", "option2", ...] representing the alternative options. Note that (1) if each option is a plain text label, these options will be rendered as buttons during a study so that participants can click on one of them; (2) if a special format "%s:name-of-stimulus" is used, FindingFive will use the corresponding stimulus defined in the study. A clickable image will be rendered if the stimulus being referenced is an image stimulus. A clickable video will be rendered if the stimulus is a video stimulus. A clickable text box will be rendered if the stimulus is a text stimulus; (3) using stimuli as choices also fully supports the key_mapping and key_only properties of choice responses (see below); (4) mixing text label options and stimulus references works as well, but sometimes it doesn’t make sense (e.g., mixing labels and videos).
  • target (optional) - a single correct answer, or a list of correct answers (as in ["correct", "also correct"]). All target values must already be listed in choices. When target is a list, participants’ choices must match exactly all listed targets. In the case of stimulus references, the target should be listed as "%s:name-of-stimulus".
  • target_match (optional, boolean) - if set to true, participants must make a choice that matches the target as defined above in order to continue the study. Default is false.
  • sample_k (optional) - instead of presenting all options defined in choices, sample k out of them randomly. If a target is defined, those options will always be presented, and an additional k - the number of targets options will be drawn from the remaining “distractors”. If left undefined, the default value is the total number of options as defined in choices.
  • key_mapping (optional) - a list of single-character individual key names (e.g., ["F", "J", ...]), each specifying which key can be pressed to choose the option presented. Note, the length of this list must be the same as sample_k, and the correspondence between options and keys are location-aligned (this means that keys are not tied to the values of options but the locations they are presented at).
  • key_only (optional) - if key_mapping is defined, setting this property to true will allow participants to respond with key presses only. Note this works for both plain text labels and referenced stimuli.
  • locations (optional) - either "fixed" (default) or "random", changing whether the locations of the choices are randomly determined on a trial
  • feedback (optional, boolean) - if a target is specified, whether or not participants will receive feedback (both visual and auditory feedback is presented). Defaults to false (i.e., no feedback even if a target is specified)
  • feedback_audio (optional, boolean) - if feedback is true, then setting this to true (default) will play a “ding!” bell sound for correct responses, and a “buzz” sound for incorrect responses. These sounds can be turned off by setting this property to false.
  • multi_select (optional, boolean) - if true (default is false), participants are allowed to select one or more options as defined in "choices". A confirm button will be available to lock in the response. Note: this option currently only works plain text labels, which are rendered as buttons.
  • incremental_feedback (optional, boolean) - if multi_select is true and target is an array, whether or not participants will receive immediate feedback after each choice they make. 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 selection.
  • ordered (optional, boolean), - if multi_select is true, whether or not the order in which targets are listed in target matters. When this is set to true, participant response is still considered incorrect even when the correct set of options are selected, but in an incorrect order.
  • layout (optional) - a list of two integers in the format of [M,N], specifying the layout of the choices. M is the number of rows and N is the number of choices per row. The product of M and N must be equal to the total number of choices. For example, when there are 4 choices, [1,4], [2,2], and [4,1] are valid layout options. Two text shortcuts "horizontal" and "vertical" are available, standing for [1, N] and [M, 1] respectively. The default (by omitting this property) is presenting all choices in a single row.
  • wrap (optional, boolean) - whether to wrap the choice options if there are too many to fit in a single row. Default is false.
  • timeout (optional) - the number of seconds for which the choice response will accept a participant response. Afterwards, 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. Default is 0, meaning that the choice response stays active indefinitely till a participant response is received.
  • hint (optional, boolean) - whether to show the text hint about which keys can be pressed to select the choices when key_mapping is defined. Default is true, displaying the hint under each choice option. When set to false, the text will go away (which will potentially make participants very confused about how to continue the study if key_only is set to true, so please use with care).
  • duration_timer (optional, boolean) - whether to show a duration timer that indicates the time elapsed since the response becomes visible. Default is false.
  • duration_timer_onset (optional) - when to show the duration timer. Default is "start", which shows the timer as soon as the response is displayed and animates a stopwatch effect. If set to "end", the duration timer only shows up when participant has made a response, with no stopwatch effect (i.e., just a measure of how long it has taken the participant to respond).
  • instruction (optional) - a short text providing the necessary instructions for participants about the current response. Default instruction is Click the answer that you think is most likely correct:. Use empty quotes "" to remove instruction.
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
rating

A rating response allows participants to express their opinion using a numeric scale. The default setup is a 5-point likert scale.

Properties:
  • type - must be specified as rating
  • min (optional, integer) - the starting point of the numeric scale. Default is 1.
  • max (optional, integer) - the endpoint of the numeric scale. Default is 5.
  • upper_bound (deprecated) - see max.
  • reverse_scoring (optional, boolean) - whether to use reverse scoring on the rating scale. Default (by omission) is false. If set to true, on a scale from 1 to 5, for example, selecting the first scale point will be recorded as 5 instead of 1, the second scale point as 4 instead of 2, and so on.
  • zero_centered (optional, boolean) - if set to true, the rating scale will be centered on 0, ranging from -max to +max. Default (by omission) is false, where the rating scale will range from min to max.
  • labels (optional, list of strings) - a list of text labels used to cosmetically replace the numeric values. Note that participant responses are still recorded in numeric terms even when labels are used. To use labels for only the ends of a rating scale (e.g., a semantic differential scale), add the labels as the first and last items of the list, and use a single quoted space for each scale point in between (for example, [“Cold”, ” “, ” “, ” “, “Warm”]).
  • duration_timer (optional, boolean) - whether to show a duration timer that indicates the time elapsed since the response becomes visible. Default is false.
  • duration_timer_onset (optional) - when to show the duration timer. Default is "start", which shows the timer as soon as the response is displayed and animates a stopwatch effect. If set to "end", the duration timer only shows up when participant has made a response, with no stopwatch effect (i.e., just a measure of how long it has taken the participant to respond).
  • instruction (optional) - a short text providing the necessary instructions for participants about the current response. Default instruction is How confident are you in your response?. Use empty quotes "" to remove instruction.
Recorded data:
  • value - the rating selected by the participant (always numeric)
  • rt - reaction time, defined as the number of milliseconds between the start of the presentation of the scale and the moment when the participant responds
text

A text response allows participants to answer a question or leave a comment by typing in a text box.

Properties:
  • type - must be specified as text
  • required (boolean, optional, default false) - whether participants must provide a response
  • max_char (optional) - the maximum number of characters allowed in this response.
  • min_seconds (optional) - the minimum number of seconds that a participant must wait before they can submit their response. Note, this does not monitor active writing. Participants can simply wait out this minimum duration and submit what they have written. This feature may have varying effectiveness in encouraging a longer response from participant to participant.
  • min_characters (optional) - the minimum number of characters that a participant must write for this response. Note that what counts as a character may differ between languages.
  • timeout (optional, numeric) - the number of seconds for which the participant can type their response. When the timeout duration passes, the text box will be immediately disabled and the response typed in by the participant will be automatically submitted.
  • target (optional) - the expected correct response, if any. All leading and trailing whitespaces in the participant’s response will be removed before being compared to the target.
  • target_match (boolean, optional, default false) - if set to true, participants must type in an answer that matches the target as defined above in order to continue the study (a good use case of this feature is to implement a passcdode).
  • spellcheck (optional, boolean) - if set to false, the text response will not alert participants about potential misspelled words, which is useful if participants are supposed to type non-dictionary words. Default (by omission) is true, meaning spellcheck will be enabled. Note that spellcheck functions are provided by the browser and may differ between browsers.
  • width (optional) - the width of the text box, preferrably in “px” (pixels).
  • height (optional) - the height of the text box, preferrably in “px” (pixels).
  • duration_timer (optional, boolean) - whether to show a duration timer that indicates the time elapsed since the response becomes visible. Default is false.
  • duration_timer_onset (optional) - when to show the duration timer. Default is "start", which shows the timer as soon as the response is displayed and animates a stopwatch effect. If set to "end", the duration timer only shows up when participant has made a response, with no stopwatch effect (i.e., just a measure of how long it has taken the participant to respond).
  • instruction (optional) - a short text providing the necessary instructions for participants about the current response. Default instruction is Type your answer here:. Use empty quotes "" to remove instruction.
Recorded data:
  • value - the text typed in by the participant
photo

A photo response allows participants to take a picture with a webcam connected to their laptop or desktop (if available) or the built-in front-facing camera on their mobile devices. Participants can always retake the picture for an unlimited number of times until they are satisified with the result.

Properties:
  • type - must be specified as photo
  • width (optional, numeric) - the width of the view finder in pixels, which will also be the width of the image saved in your session data. Default is "auto", meaning that the width will be adaptive to the device that the participant is using. If your study will run on multiple devices (including mobile devices), it is highly recommended to leave this at its default "auto" setting (or simply omit it).
  • height (optional, numeric) - the height of the view finder in pixels, which will also be the height of the image saved in your session data. Default is "auto", meaning that the height will be adaptive to the device that the participant is using. If your study will run on multiple devices (including mobile devices), it is highly recommended to leave this at its default "auto" setting (or simply omit it).
  • mirror_mode (optional, boolean) - whether or not to use a mirror image in the view finder (how the participants see themselves). Default is true, meaning the mirror image will be used even if you don’t add this property. Most video chat software displays camera images in the mirror mode, so we highly recommend not changing this setting unless motivated by your experimental design.
  • frame_rate (optional, integer) - the frame rate at which the view finder refreshes itself. Default is 30, meaning that the view finder refreshes 30 times per second to ensure smooth motion in the camera feed. We do not recommend changing this value unless motivated by your experimental design: setting it to a value too low will cause stuttering in the view finder, making it difficult to take a clear picture; setting it to a value too high will unnecessarily tax the participant’s computer, potentially resulting in idiosyncractic technical problems.
  • duration_timer (optional, boolean) - whether to show a duration timer that indicates the time elapsed since the response becomes visible. Default is false.
  • duration_timer_onset (optional) - when to show the duration timer. Default is "start", which shows the timer as soon as the response is displayed and animates a stopwatch effect. If set to "end", the duration timer only shows up when participant has made a response, with no stopwatch effect (i.e., just a measure of how long it has taken the participant to respond).
  • instruction (optional, text) - a short text providing instructions for participants about the current response. A default instruction does not exist for the photo response, as its interface is already highly intuitive. You can however add a custom instruction by setting this property to any desired text.
Recorded data:
  • value - the name of the image file that is saved; this image file is included in the downloadable zip archive containing your participant data.
  • rt - the time in milliseconds that participants take to snap the picture.
audio

An audio response allows participants to record their answer. Participants can always replay their recording to examine its content. If rerecording is allowed, they can rerecord themselves for an unlimited number of times until they are satisified with the result.

Properties:
  • type - must be specified as audio
  • padding (optional, default at 500) - the number of milliseconds it will continue to record after participants hit stop. Default is 500. This parameter prevents participants from cutting off their recording too quickly (i.e., hitting stop while still speaking).
  • auto_start (optional, boolean) - whether the audio response will start recording automatically. Default is false.
  • key_stop (optionl, character) - a single character (excluding function keys such as ctrl, atl, command, etc) that can be pressed to stop the recording. Default is " ", the space bar.
  • rerecording_allowed (optional, boolean) - whether participants can rerecord themselves (for each audio response). Default is true. When set to false, participants can still replay their own recording, but will have no means to overwrite it.
  • onset_detection (optional, boolean) - whether to perform onset detection in this recording based on real-time analysis of recording volume. If set to true, the audio response will record the time (in milliseconds) at which the participant first start speaking (or making a loud noise). Default is false.
  • onset_sensitivity (optional, integer) - an integer number between 1 and 99, which represents the sensitivity of the onset detection feature, with 1 being the least sensitive, and 99 being the most sensitivity. Default is 50 (which can be omitted). We don’t recommend changing this setting unless there are hypothesis-driven reasons for your study to use a lower or higher sensitivity setting.
  • speech_to_text (optional, boolean) - whether to automatically transcribe the recording to English text. Important: this is and will remain a highly experimental feature. Please read this forum post before using this feature in your study.
  • duration_timer (optional, boolean) - whether to show a duration timer that indicates the time elapsed since the response becomes visible. Default is false.
  • duration_timer_onset (optional) - when to show the duration timer. Default is "start", which shows the timer as soon as the response is displayed and animates a stopwatch effect. If set to "end", the duration timer only shows up when participant has made a response, with no stopwatch effect (i.e., just a measure of how long it has taken the participant to respond).
  • instruction (optional) - a short text providing the necessary instructions for participants about the current response. Default instruction is Please speak into the microphone clearly.. Use empty quotes "" to remove instruction.
Recorded data:
  • value - the name of the sound file that is saved; this sound file is included in the downloadable zip archive containing your participant data.
  • rt - the onset time if onset detection is turned on; empty otherwise
mouse_reset

A mouse reset response displays an element that participants must interact with to advance the trial. The element is either a button, or a bullseye icon that participants must hover the mouse over before it turns into a button. This is most useful in mouse tracking studies, in order to force the participant’s mouse to be at a certain position. See also the mouse_reset trial template.

Properties:
  • type - must be specified as mouse_reset
  • hover_required (boolean, optional) - whether or not the participant must hover thier mouse in position for a designated amount of time before the button appears. Default is false. When set to true, a bullseye icon will indicate where participants must hover their mouse.
  • hover_time (optional) - the number of seconds for which the participant’s mouse must hover over the bullseye icon when hover_required is set to true. Fractions supported. Default is 2.
  • button_content (optional) - the text content of the final button. Default is CONTINUE.
  • button_alignment (optional) - one of "left", "right", or "center", indicating how the button should be aligned (justified). Default is "center". Interacts with the reset_location property of a mouse_reset trial template to allow for precise placement. For example, if the button is placed in the center right of the screen, setting "button_alignment" to "right" will ensure that the button is rendered as close to the right edge of the trial window as possible.
  • instruction_alignment (optional) - one of "left", "right", or "center", indicating how the response instruction should be aligned (justified). Default is "center".
  • alignment (optional) - a shorthand for the combined properties button_alignment and instruction_alignment. Default is "center".
  • duration_timer (optional, boolean) - whether to show a duration timer that indicates the time elapsed since the response becomes visible. Default is false.
  • duration_timer_onset (optional) - when to show the duration timer. Default is "start", which shows the timer as soon as the response is displayed and animates a stopwatch effect. If set to "end", the duration timer only shows up when participant has made a response, with no stopwatch effect (i.e., just a measure of how long it has taken the participant to respond).
  • instruction (optional) - a short text providing the necessary instructions for participants about the current response. Default instruction is Click the [button_content]button to advance.. Use empty quotes "" to remove instruction.
Recorded data:
  • No data is recorded for mouse reset responses. For duration, see the trial duration.

Background responses

Background responses are invisible to participants. They are most commonly used to record participant behavior during a trial covertly, or in conjunction with a visible response.

background_audio

A background audio response allows researchers to record any sounds captured by participants’ microphone during a trial, without any interactions required from participants (this feature works most reliably in Chrome and Firefox).

Please clearly communicate to your participants that they are being recorded on relevant trials.

Properties:
  • type - must be specified as background_audio (note the underscore)
  • volume_visualizer (boolean, optional, default false) - whether to display a volume bar indicating to the participants that their voices are being recorded. Default is false, meaning not displaying the visualizer, in which case it is highly recommended to inform participants they are being recorded.
  • duration (numeric or string, optional, default 0) - the length of this background audio recording in seconds. Decimals are supported. For example, setting a value of 1.5 will result in the background audio response automatically stopping collecting data after 1.5 seconds. If the background audio response is the only response on a trial, the trial will automatically advance once the set duration passes. Alternatively, a special syntax "%duration:stimulus_group_name+2.0" can be used to specify the duration relative to a stimulus of a certain stimulus group on the same trial. In the example above, the duration of the background audio response will be the duration of the stimulus that belogs to the stimulus group "stimulus_group_name" plus 2 seconds. Note that this will only work if the stimulus has an inherent (like an audio or video) or specified duration. You must also define the stimulus groups manually for those stimuli.
  • onset_detection (optional, boolean) - whether to perform onset detection in this recording based on real-time analysis of recording volume. If set to true, the audio response will record the time (in milliseconds) at which the participant first start speaking (or making a loud noise). Default is false.
  • onset_sensitivity (optional, integer) - an integer number between 1 and 99, which represents the sensitivity of the onset detection feature, with 1 being the least sensitive, and 99 being the most sensitivity. Default is 50 (which can be omitted). We don’t recommend changing this setting unless there are hypothesis-driven reasons for your study to use a lower or higher sensitivity setting.
  • speech_to_text (optional, boolean) - whether to automatically transcribe the recording to English text. Important: this is and will remain a highly experimental feature. Please read this forum post before using this feature in your study.
Recorded data:
  • value - the name of the sound file that is saved; this sound file is included in the downloadable zip archive containing your participant data.
  • rt - the onset time if onset detection is turned on; empty otherwise
keypress

A keypress response records all keys that a participant presses during a trial.

Properties:
  • type - must be specified as keypress
  • multiple (boolean, optional, default true) - if true, then record all key presses during a trial; if false, only the first key press will be recorded.
  • whitelist (list of characters, optional) - a list of characters, such as ["d", " ", "k"], to indicate which keys FindingFive should monitor. Key presses outside the whitelist are ignored and not recorded.
  • blacklist (list of characters, optional) - a list of characters to indicate which keys FindingFive should not monitor. Key presses outside the blacklist are recorded.
Recorded data:
  • value - the name of the key pressed by the participant
  • rt - the duration in milliseconds between the last key press and the current one; for the first key press, rt is the duration between the activation of this response and the first key press.
mouse_position

A mouse position response records the XY coordinates of the mouse at regular intervals during a trial

Properties:
  • type - must be specified as mouse_position
  • sampling_rate - the number of coordinates recorded per second at equal intervals. For example, a value of 10 will result in 10 mouse coordinates per second, recorded 100ms apart.
  • reference_point (optional) - one of "topleft", "topright", "center", "bottomleft, and "bottomright", indicating where in the participant’s browser window counts as the (0,0) position. All X and Y coordinates will be relative to this reference point, with a negative number indicating left of (or above) the point, and a positive number right of (or below) the point. Default is "topleft".
  • proportional (boolean, optional) - Default is false. If set to true, then X and Y coordinates are reported as a proportion of the size of the browser window (which is equivalent to the full screen size except in the case of MTurk studies, where the full screen mode is not possible). The proportion will be a fractional number between 0 and 1, -1 and 0, -0.5 and 0.5 depending on the choice of the reference_point. For example, when reference_point is set to "center" by default, the proportional coordinates will be between -0.5 and 0.5 since the maximum distance for the mouse to travel in all directions relative to the reference point is half of the browser window’s width or height. When the reference point is set to "topleft", coordinates will be between 0 and 1, since the mouse can travel the full distance of the window to the right of or below the top left corner. When the reference point is set to "topright", X coordinates will be from 0 to -1, and Y coordinates will be from 0 to 1, since the mouse can travel the full distance of the window to the left of or below the top right corner. See the Mouse-Tracking Tutorial for a visual depiction of recorded coordinates for each reference point.
Recorded data:
  • value - the X and Y coordinates of the mouse position, in the format of X|Y (e.g., 11|23, -343|281).
  • rt - the time at which the coordinates are recorded, in milliseconds, relative to the onset of the trial.