Stimuli

A stimulus is defined by a property-value pair inside the top-level property stimuli in a study runtime specification. Its key serves as the name of the stimulus, which can be referenced in other parts of the specification. Its value defines the type, content, and other properties that apply to a stimulus.

For example, the following snippet

"training-prompt": {
    "type": "text",
    "content": "Please listen carefully to the next sentence"
}

defines a stimulus of type text with the name training-prompt, which will display the content “Please listen carefully to the next sentence” when used in a trial template.

Common properties

The properties type and content in the above example are special keywords that are used to specify the properties of a stimulus. All stimuli share three common properties:

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

  • content - either the text to be displayed, or a pointer (e.g., a file name) to the underlying resource

  • parent (optional) - the name of another stimulus; if specified, then the properties of the other stimulus will be inherited by this stimulus, unless a property of the same name is defined in this stimulus.

  • delay (optional) - delay the onset of a stimulus, relative to (1) the onset of a trial if there are no stimuli acting as barriers or (2) the end of the last stimulus acting as a barrier, by a certain number of seconds (fractions are supported).

    Default (by omission): 0, meaning no delay

    Note

    • This property is used for presenting multiple stimuli on a trial in a sequence. To implement inter-trial intervals, see the delay parameter in trial templates instead.
    • The delaying of multiple stimuli on a trial does NOT have a chain effect. That is, the delay of any stimulus on a trial is always relative to the onset of that trial.
  • duration (optional) - keep a text/image stimulus visible, or an audio/video stimulus audible/visible for a certain number of seconds (fractions are supported) relative to the onset of that stimulus.

    Warning

    In most cases, it is far more common to manipulate the duration of a trial instead. Please make sure you really intend to specify a duration for a specific stimulus before using this feature.

    Default (by omission): -1, meaning that the stimulus, once triggered, will stay on a trial indefinitely.

    Warning

    On a given trial, responses on that trial will be hidden until the onset of all stimuli have been triggered (i.e., immediately after the passage of delay).

    This means that, for example, if participants should wait until an audio stimulus finishes playing before responding, it is desirable to specify a delay property for the corresponding response that is the same as the duration of the stimulus.

In addition, a stimulus can have any custom-named property that serves as an attribute of the stimulus. Check out an important use of attributes in Stimulus patterns.

Static stimuli

These types of stimuli are static in the sense that the rendering of their content is not contigent upon participants’ actions. For most studies, static stimuli are the most useful and common types of stimuli to use.

text

A text stimulus displays a block of text

Properties:
  • type - must be specified as text
  • content - the text to be displayed; a limited set of HTML tags [1] are supported.
  • color (optional) - the color of the text stimulus (e.g., common color names such as “red”, “darkgreen”, or hex codes like #FF6600)
  • size (optional) - the font size of the text stimulus, specified using HTML font sizes such as “px”, “em”, or “rem”. The rendered outcome might differ across browsers and devices.
  • alignment (optional, “left” by default) - the alignment of text; options are “left”, “right” and “center”.

Note

For the next three stimulus types, one needs to upload external stimulus files to FindingFive. Stimulus files on FindingFive are accessible across studies within the same account. That means if you have uploaded “a.jpg” to Study A, simply referring to “a.jpg” in the content property of a stimulus in Study B is sufficient. There’s no need to upload the file again.

image

An image stimulus displays an image

Properties:
  • type - must be specified as image
  • content - the file name of the image file (you will be prompted for uploading the file). Format support is dependent on the participants’ browser. In most cases, common image formats such as .jpg, .png, and .gif are safe choices.
  • width (optional) - the width at which the image is displayed (e.g., 50%, 200px, or any other CSS width control units)
audio

An audio stimulus plays an audio clip

Properties:
  • type - must be specified as audio
  • content - the file name of the audio file (you will be prompted for uploading the file). Format support is dependent on the participants’ browser (see the note below video for recommended practices).
  • barrier (optional) Default is true; if set to true, then all subsequent stimuli and responses will not be displayed until this audio clip finishes playing. Otherwise if set to false.
  • delay (optional but recommended) - how many seconds to delay before playing the audio. If not set, the audio may appear to start abruptly on a new trial (a reasonable value is 0.3, introducing a minor delay).
  • autoplay (optional) - whether or not to start playing the audio without participant action. Default is true. Setting this option to false nullifies the delay parameter.
  • visible (optional) - whether audio controls should be displayed. Default is true. If set to false, the audio will play in the background instead. Obviously, do not set autoplay to false if the audio plays in the background only.
video

A video stimulus plays a video clip

Properties:
  • type - must be specified as video
  • content - the file name of the video file (you will be prompted for uploading the file). Format support is dependent on the participants’ browser (see the note below for recommended practices).
  • width - (optional) the width of the video, in pixels (e.g., “200px”). Height will be automatically adjusted to preserve the original aspect ratio. Default is the actual size of the video. This parameter affects the video when used as a choice response option as well.
  • barrier (optional) Default is true; if set to true, then all subsequent stimuli and responses will not be displayed until this video clip finishes playing. Otherwise if set to false.
  • replyable (optional) Default is false; if set to true, video stimuli will be greyed out once finished playing and a “replay” button will display, allowing participants to replay a video stimulus.
  • delay (optional but recommended) - how many seconds to delay before playing the audio. If not set, the audio may appear to start abruptly on a new trial (a reasonable value is 0.3, introducing a minor delay).
  • autoplay (optional) - whether or not to start playing the video without participant action. Default is true. Setting this option to false nullifies the delay parameter. This parameter affects the video when used as a choice response option as well.
  • visible (optional) - Default is true. If set to false, the video will play in the background instead (which probably doesn’t make sense in most cases).

Note

Encoding Audio and Video stimuli for maximum compatibility

The support for audio and video stimuli in FindingFive is provided by HTML5, which, unfortunately, is a little inconsistent across browsers and operating systems (but it keeps getting better!). To make sure the audio and video stimuli play successfully for participants, we recommend using:

  • mp3 for audio stimuli, and mp4 (encoded with the h.264-x264 codec) for video stimuli. This setting tends to work well across all major browsers (Chrome, Firefox and Safari) and all major operating systems (Windows, Mac, and Linux). However, there is a chance that older Linux systems with older browsers will not support these formats.

Software for converting between audio and video formats

There are many ways to converting your audio and video stimuli to the desired format. For audio transcoding, check out fre:ac. For video transcoding, we recommend using the free, open-source program HandBrake.

Interactive stimuli

tokenized_text

A tokenized-text stimulus is similar to the text stimulus, with additional options for manipulating the stimulus on a token-by-token basis (in most cases, a token is a word). A tokenized-text stimulus can be particularly useful for creating a self-spaced reading study.

Properties:
  • type - must be specified as tokenized_text
  • content - the text to be displayed; for example, in a typical self-paced reading study, this should be a single sentence.
  • barrier (optional) Default is true; if set to true, then all subsequent stimuli and responses will not be displayed until this tokenized text stimulus displays all its content (self-paced or not). Otherwise if set to false.
  • delimiter - A character or a string that serves as the boundary for splitting content into a list of tokens. Defaults to a single space character (i.e., " ").
  • self_paced (boolean) - If true, then the display of the tokens in a tokenized text stimulus needs to be triggered by user interaction, and reaction time for each token is recorded; if false, then a tokenized text stimulus will be automatically presented.
  • key_advance - the key that a participant should press to advance the presentation of a tokenized text stimulus, only if self_paced is set to true.
  • speed - the speed, in characters per second, at which a tokenized text stimulus is presented, only if self_paced is set to false.
  • mode - the mode in which the tokenized text stimulus is displayed. Three options are possible: "plain", where tokens are displayed in sequence, "masked", where only one active token is displayed and other tokens explicitly masked (see below for more controls for this mode), and "singleton", where only one active token is displayed with all other tokens invisible. Defaults to "plain".
  • mask_char - a character used to mask inactive tokens if the mode is "masked". For example, if the mask character is “#”, when the token TOKEN is no longer active, it will be displayed as “#####”. Defaults to "#".
  • forward_mask (boolean, optional) - if set to true, then tokens both preceeding and following the active token are simultaneously displayed in the mask character; if set to false, then only tokens preceeding the active token are displayed in the mask character, while tokens following the active token are invisible. Defaults to false.
  • regex (boolean, optional) - if set to true, the delimiter is interpreted as a regular expression instead of a string. Defaults to false.

Footnotes

[1]The following HTML tags are currently allowed in a text stimulus: <abbr>, <acronym>, <b>, <blockquote>, <code>, <em>, <i>, <li>, <ol>, <strong>, <ul>, <p>.