Skip to content

Basic Trial Template

The basic trial template structures each trial by presenting stimuli above responses in a vertical layout. In any trial using this template, responses always appear below stimuli. This design reflects a common and intuitive way of structuring trials in psychological research. Additionally, because both stimuli and responses are optional, the basic trial template allows for considerable flexibility—trials may consist of only stimuli, only responses, or both, depending on the study's needs.

Given the many configurable settings within a trial template, the following sections categorize these properties by function—such as stimulus behavior, timing, and trial progression—to facilitate navigation and conceptual clarity.

Looking for Trial Template Types "instruction" and "AFC"?

These trial templates are now deprecated and should not be used in studies anymore. For existing studies that have these trial template types, simply set the "type" property to "basic". For archived documentation on these template types, check out this page.

Stimulus Properties

type

  • Definition: The type of trial template
  • Possible values: For basic trial templates, must be specified as basic
1
2
3
4
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2"]
}

stimuli

  • Definition: A list of items specifying which stimuli to be used in a trial template and how they are used (such as the locations of stimuli and whether multiple stimuli are presented on the same trial).
  • Possible values:
    • a simple option that places stimuli in standard locations
    • a custom option that allows researchers to manipulate the locations of stimuli
  • Definition: This option takes a list of stimulus names (e.g., ["s1", "s2", "s3"]) that define which stimuli to present on each realized instance of this trial template. These stimuli will be presented in standard locations.
  • Possible values: A list of stimulus names (e.g., ["s1", "s2", "s3"]). Use nested lists to present multiple stimuli on a single trial (e.g., ["s1", ["s2", "s3"]]).

  • Example code: For example, consider the trial template "T1" defined as:

    1
2
3
4
    "T1": {
  "type": "basic",
  "stimuli": ["s1", ["s2", "s3"], "s4"]
}

    This trial template will generate a total of three trials: s1 will be displayed on the first trial, s2 and s3 will be displayed on the second trial, and s4 will be displayed on the third trial. The locations of these stimuli are chosen by FindingFive - when there's one stimulus per trial, the stimulus will be in the center of the trial; when there are more than one stimulus per trial, the stimuli will be placed in intuitive default locations.

  • Definition: A list of dictionaries of stimulus names, paired with their locations in a 3x3 grid. Optionally, one can also specify whether to randomly shuffle the stimuli across the defined locations.
  • The 3x3 grid is organized as follows:

    grid

  • Possible values: A list of dictionaries specified in the form: {"which": [LIST_OF_STIMULI], "location": [LIST_OF_LOCATIONS], "randomize_location": true or false}. Note that "randomize_location" is optional and its default value is false. Also note that with the custom option, each dictionary refers to stimuli-location pairings for a single trial. Include one dictionary for each desired trial.

  • Example code: For example, to place two stimuli on a single trial so that one is at the top left corner and the other at the bottom right corner, one can specify:

    1
2
3
4
5
6
    "T1": {
  "type": "basic",
  "stimuli": [{"which": ["s1", "s2"], "location": [1, 9],
  "randomize_location": true},
  {"which": ["s3", "s4"], "location": [1, 3]}]
}

    In the above trial template, s1 and s2 will be displayed on the first trial. Because randomize_location is specified as true, s1 and s2 will be randomly placed in the top left corner (location 1) and bottom right corner (location 9). s3 and s4 will be displayed on the second trial. Because randomize_location is not specified (equivalent to "randomize_location": false), s3 will appear in the top left corner (location 1) and s4 will appear in the top right corner (location 3).

Stimulus names can also be a special syntax that refers to participant responses collected on previous trials of the same experiment (carryover responses). This can be useful for experimental designs where the participant is asked to review or judge their own responses in perception or decision making tasks. At the time being, FindingFive supports using participant data collected from text and audio responses as text and audio stimuli, respectively.

The special syntax is:

1
"%r:BlockName|TrialTemplateName|ResponseName"

Each instance of this special stimulus name carries over exactly one participant response. In a typical design, the same ResponseName response may be used many times with different stimuli on the same trial template. To carry over multiple participant responses that can be matched by this special syntax, simply use as many instances of this special stimulus name as needed. For example:

1
2
3
4
5
6
7
8
"TestingTrialTemplate": {
    "stimuli": ["%r:TrainingBlock|AudioRecordingTrial|AudioResponse",
                "%r:TrainingBlock|AudioRecordingTrial|AudioResponse",
                "%r:TrainingBlock|AudioRecordingTrial|AudioResponse",
                "%r:TrainingBlock|AudioRecordingTrial|AudioResponse",
                "%r:TrainingBlock|AudioRecordingTrial|AudioResponse"],
    "responses": ["SomeResponse"]
}

The above trial template will create 5 different trials, each of which uses a different response that has been collected on the AudioRecordingTrial in the TrainingBlock (note you must make sure that that trial has collected at least 5 AudioResponses).

By default, you do not need to define a separate stimulus for carryover responses used as stimuli. However, in the event that customization is necessary, you can create a stimulus of the same name. For example, we can create a stimulus named %r:TrainingBlock|AudioRecordingTrial|AudioResponse after we have used the same syntax in the "stimuli" property of the above trial template. Then, we would like to make the stimulus invisible and truncated to only 5 seconds (let’s pretend the original audio response collected 10s of recording):

1
2
3
4
5
{
    "type": "audio",
    "visible": false,
    "duration": 5
}

Importantly, as a general rule for using carryover responses, those responses must have been already collected in an earlier block than the block referencing them.

stimulus_pattern

Definition: A dictionary that specifies how the supplied stimuli are used on realized trials. The dictionary usually consists of a set of optional properties for tweaking the presentation of stimuli on trials generated from a template, such as:

1
2
3
4
5
6
{
    "order": "some_order",
    "attribute": "some_attribute",
    "pre_shuffle": false,
    "limit": 5
}

"attribute"

  • Definition: A stimulus can have custom-named properties that serve as attributes of the stimulus. This is useful for controlling the presentation pattern of particular types of stimuli, when used together with some of the below options for "order".
  • Possible values: A custom-named property defined for one or more of the stimuli listed in the "stimuli" property of a trial template.
  • Default: there is no default for this property as it is completely optional. That is, the "attribute" property can be omitted from "stimulus_pattern".

For example, one can set a custom attribute called "grammatical" with values of either true or false for a group of text stimuli:

1
2
3
4
5
{
  "type": "text",
  "content": "It rained yesterday",
  "grammatical": true
}

and

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "type": "text",
  "content": "I love eating many ice-creams",
  "grammatical": false
}
````

Then, one can alternate the presentation of grammatical and ungrammatical sentences by using the following stimulus pattern setup:

```json linenums="1"
"stimulus_pattern": {"order": "alternate",
                     "attribute": "grammatical"}

"order"

  • Definition: The order in which stimuli within a trial template are presented on trials generated from this template.
  • Possible values: "fixed", "random", "pseudorandom", "ascending", "descending", "alternate", "every". See the following tabs for details on each of these.
  • Default: "fixed".

"fixed" presents stimuli in the same order as they are listed in the "stimuli" property of the trial template. For example:

1
2
3
4
5
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2"],
  "stimulus_pattern": {"order": "fixed"} // this is the default and can be omitted
}

A total of two trials will be generated from this trial template: the first trial presents the stimulus "s1" and the second trial "s2". In other words, stimuli are presented in the order they are listed in the "stimuli" property due to the "fixed" order. This is the default and can be omitted.

"random" presents stimuli randomly, using true randomization that is generated each time a participant views the study, with no counterbalancing within or between participants.

1
2
3
4
5
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2"],
  "stimulus_pattern": {"order": "random"}
}

In the above code, the presentation order of stimuli "s1" and "s2" is randomized per participant, and per instance of the trial template. For example, if the same trial template is used multiple times in a study, the trials generated from the template will be randomized separately for each occurrence of that trial template for each participant.

"pseudorandom" presents stimuli randomly, subject to the constraint that stimuli with a designated custom attribute (in this example, "ungrammatical") will appear in a row at least "min_N" times (defaults to 1) and at most "max_N" times (defaults to, and is always at least equal to, "min_N").

1
2
3
4
5
6
7
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2"],
  "stimulus_pattern": {"order": "pseudorandom",
                       "attribute": "ungrammatical",
                       "min_N": 2, "max_N": 4}
}
In the above code, stimuli are randomized per participant, so that ungrammatical stimuli (those with custom attribute "ungrammatical" set to true) are presented at least twice in a row, but no more than 4 times consecutively.

"ascending" presents stimuli in increasing order by the value of a designated custom attribute (in this example, "length").

Consider that the following stimuli are defined in your study:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
  "singleShort1": {"type": "image",
                   "content": "new-ambi1-a-1.jpg",
                   "length": 1
                  },
  "singleShort2": {"type": "image",
                   "content": "new-ambi1-a-2.jpg",
                   "length": 2
                  },
  "singleShort3": {"type": "image",
                   "content": "new-ambi1-a-3.jpg",
                   "length": 3
                  },
  "singleShort4": {"type": "image",
                   "content": "new-ambi1-a-4.jpg",
                   "length": 4
                  },
  "singleShort5": {"type": "image",
                   "content": "new-ambi1-a-5.jpg",
                   "length": 5
                  }

The following trial template:

1
2
3
4
5
6
7
8
"T1": {
  "type": "basic",
  "stimuli": ["singleShort1", "singleShort2",
              "singleShort3", "singleShort4",
              "singleShort5"],
  "stimulus_pattern": {"order": "ascending",
                       "attribute": "length"}
}
presents the stimuli in the order that the value of "length" increases (singleShort1, singleShort2, singleShort3, etc.). Intuitively, changing "ascending" to "descending" has the exact opposite effect.

Note that if two or more stimuli have the same value for "length", then their relative order can be randomized setting "pre_shuffle" to true:

1
2
3
4
5
6
7
8
9
"T1": {
  "type": "basic",
  "stimuli": ["singleShort1", "singleShort2",
              "singleShort3", "singleShort4",
              "singleShort5"],
  "stimulus_pattern": {"order": "ascending",
                       "attribute": "length",
                       "pre_shuffle": true}
}
If the values of the target attribute are all unique, then "pre_shuffle" has no effect.

"descending" presents stimuli in decreasing order by the value of a designated custom attribute (in this example, "length").

Consider that the following stimuli are defined in your study:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
  "singleShort1": {"type": "image",
                   "content": "new-ambi1-a-1.jpg",
                   "length": 1
                  },
  "singleShort2": {"type": "image",
                   "content": "new-ambi1-a-2.jpg",
                   "length": 2
                  },
  "singleShort3": {"type": "image",
                   "content": "new-ambi1-a-3.jpg",
                   "length": 3
                  },
  "singleShort4": {"type": "image",
                   "content": "new-ambi1-a-4.jpg",
                   "length": 4
                  },
  "singleShort5": {"type": "image",
                   "content": "new-ambi1-a-5.jpg",
                   "length": 5
                  }
The following trial template:

1
2
3
4
5
6
7
8
"T1": {
  "type": "basic",
  "stimuli": ["singleShort1", "singleShort2",
              "singleShort3", "singleShort4",
              "singleShort5"],
  "stimulus_pattern": {"order": "descending",
                       "attribute": "length"}
}
presents the stimuli in the order that the value of "length" decreases (singleShort5, singleShort4, singleShort3, etc.). Intuitively, changing "descending" to "ascending" has the exact opposite effect.

Note that if two or more stimuli have the same value for "length", then their relative order can be randomized setting "pre_shuffle" to true:

1
2
3
4
5
6
7
8
9
"T1": {
  "type": "basic",
  "stimuli": ["singleShort1", "singleShort2",
              "singleShort3", "singleShort4",
              "singleShort5"],
  "stimulus_pattern": {"order": "descending",
                       "attribute": "length",
                       "pre_shuffle": true}
}
If the values of the target attribute are all unique, then "pre_shuffle" has no effect.

"alternate" presents stimuli so that they alternate between values of a defined custom attribute.

Consider that the following stimuli are defined in your study:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
  "singleShort1": {"type": "image",
                   "content": "new-ambi1-a-1.jpg",
                   "difficulty": "easy"
                  },
  "singleShort2": {"type": "image",
                   "content": "new-ambi1-a-2.jpg",
                   "difficulty": "easy"
                  },
  "singleShort3": {"type": "image",
                   "content": "new-ambi1-a-3.jpg",
                   "difficulty": "easy"
                  },
  "singleShort4": {"type": "image",
                   "content": "new-ambi1-a-4.jpg",
                   "difficulty": "hard"
                  },
  "singleShort5": {"type": "image",
                   "content": "new-ambi1-a-5.jpg",
                   "difficulty": "hard"
                  }

The following trial template then presents the stimuli so that "easy" and "hard" alternate:

1
2
3
4
5
6
7
8
"T1": {
  "type": "basic",
  "stimuli": ["singleShort1", "singleShort2",
              "singleShort3", "singleShort4",
              "singleShort5"],
  "stimulus_pattern": {"order": "alternate",
                       "attribute": "difficulty"}
}

"every" presents one stimulus with a defined custom attribute after presenting N-1 stimuli without this attribute. An additional property "N" must also be specified.

Consider that the following stimuli are defined in your study:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
  "singleShort1": {"type": "image",
                   "content": "new-ambi1-a-1.jpg",
                  },
  "singleShort2": {"type": "image",
                   "content": "new-ambi1-a-2.jpg",
                  },
  "singleShort3": {"type": "image",
                   "content": "new-ambi1-a-3.jpg",
                  },
  "singleShort4": {"type": "image",
                   "content": "new-ambi1-a-4.jpg",
                   "difficult": true
                  },
  "singleShort5": {"type": "image",
                   "content": "new-ambi1-a-5.jpg",
                   "difficult": true
                  },
  "singleShort6": {"type": "image",
                   "content": "new-ambi1-a-6.jpg",
                  }
The following trial template:

1
2
3
4
5
6
7
8
9
"T1": {
  "type": "basic",
  "stimuli": ["singleShort1", "singleShort2",
              "singleShort3", "singleShort4",
              "singleShort5", "singleShort6"],
  "stimulus_pattern": {"order": "every",
                       "attribute": "difficult"}
  "N": 3
}
presents 2 stimuli ("N"-1) without custom property "difficult", then presents 1 stimulus with "difficult" : true, and repeats until all stimuli are displayed (e.g., singleShort1, singleShort2, singleShort4, singleShort3, singleShort6, singleShort5).

"preshuffle"

  • Definition: Whether or not to randomize the stimulus order as given in the "stimuli" property of a trial template before applying the specified pattern
  • Possible values: true or false
  • Default: false
  • This property is ignored if "order" is "fixed" or "random"
  • In cases where "order" implies strict ordering (such as "ascending"), "pre_shuffle" only affects cases where attribute values are the same.

Consider that the following stimuli are defined in your study:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
  "singleShort1": {"type": "image",
                   "content": "new-ambi1-a-1.jpg",
                   "difficulty": "easy"
                  },
  "singleShort2": {"type": "image",
                   "content": "new-ambi1-a-2.jpg",
                   "difficulty": "easy"
                  },
  "singleShort3": {"type": "image",
                   "content": "new-ambi1-a-3.jpg",
                   "difficulty": "easy"
                  },
  "singleShort4": {"type": "image",
                   "content": "new-ambi1-a-4.jpg",
                   "difficulty": "hard"
                  },
  "singleShort5": {"type": "image",
                   "content": "new-ambi1-a-5.jpg",
                   "difficulty": "hard"
                  }

Consider the effects of "pre_shuffle":

1
2
3
4
5
6
7
8
9
"T1": {
  "type": "basic",
  "stimuli": ["singleShort1", "singleShort2",
              "singleShort3", "singleShort4",
              "singleShort5"],
  "stimulus_pattern": {"order": "alternate",
                       "attribute": "difficulty",
                       "pre_shuffle": false}
}
With "pre_shuffle" set to false (which can be omitted since it's the default), the stimuli are always going to be presented in the order "singleShort1", "singleShort4", "singleShort2", "singleShort5", "singleShort3"*

1
2
3
4
5
6
7
8
9
"T1": {
  "type": "basic",
  "stimuli": ["singleShort1", "singleShort2",
              "singleShort3", "singleShort4",
              "singleShort5"],
  "stimulus_pattern": {"order": "alternate",
                       "attribute": "difficulty",
                       "pre_shuffle": true}
}
With "pre_shuffle" set to true, although "easy" and "hard" still alternate, it is possible to obtain a sequence such as "singleShort2", "singleShort5", "singleShort1", "singleShort4", "singleShort3". That is, the order in which stimulus names are listed in the trial template has no effect on the generated alternating order anymore.

"N"

  • Definition: This property is required when "order" is "every", meaning that for every N trials, present one stimulus with the attribute specified in "every" (that is, present one trial with the attribute of interest after every N-1 trials without the attribute).
  • Possible values: An integer
  • Default: there is no default as this property is only required for some types of "order" and should be omitted in most cases.

Consider that the following stimuli are defined in your study:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
  "singleShort1": {"type": "image",
                   "content": "new-ambi1-a-1.jpg",
                  },
  "singleShort2": {"type": "image",
                   "content": "new-ambi1-a-2.jpg",
                  },
  "singleShort3": {"type": "image",
                   "content": "new-ambi1-a-3.jpg",
                  },
  "singleShort4": {"type": "image",
                   "content": "new-ambi1-a-4.jpg",
                   "difficult": true
                  },
  "singleShort5": {"type": "image",
                   "content": "new-ambi1-a-5.jpg",
                   "difficult": true
                  },
  "singleShort6": {"type": "image",
                   "content": "new-ambi1-a-6.jpg",
                  }
The following trial template:

1
2
3
4
5
6
7
8
9
"T1": {
  "type": "basic",
  "stimuli": ["singleShort1", "singleShort2",
              "singleShort3", "singleShort4",
              "singleShort5", "singleShort6"],
  "stimulus_pattern": {"order": "every",
                       "attribute": "difficult"}
  "N": 3
}
presents 2 stimuli ("N"-1) without custom property "difficult", then presents 1 stimulus with "difficult" : true, and repeats until all stimuli are displayed (e.g., singleShort1, singleShort2, singleShort4, singleShort3, singleShort6, singleShort5).

"limit"

  • Definition: When set to K, an integer, FindingFive applies the stimulus pattern as defined and then shows only the first K stimuli
  • Possible values: An integer smaller than or equal to the total number of stimuli that can be rendered from this trial template
  • Default: there is no default as this property is completely optional and can be omitted.

The most common use of "limit" is to randomly sample a subset of stimuli from a given collection:

1
2
3
4
5
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2", "s3", "s4"],
  "stimulus_pattern": {"order": "random", "limit": 2}
}
The above code first randomizes the 4 stimuli per participant, then presents the first 2. In effect, this means that each participant will see two randomly selected stimuli from the four available options.

Response Properties

responses

  • Definition: A list of response names representing responses to be used on realized trials.
  • Possible values: Single plain text label (e.g., ["response1"]) or nested list (e.g., [["response1", "response2"]]). Nested lists can be used to present more than one response in a single realized trial.

1
2
3
4
5
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2"],
  "responses": ["r1"]
}
The above code presents "r1" for both trials (one presenting "s1" and one presenting "s2").

1
2
3
4
5
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2"],
  "responses": ["r1", "r2"]
}
The above code presents r1 for the first trial (which presents s1) and r2 for the second trial (which presents s2).

1
2
3
4
5
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2"],
  "responses": [["r1", "r2"]]
}
The above code presents both r1 and r2 for both the trial presenting s1 and the trial presenting s2.

response_pairing

  • Definition: When both the "stimuli" and the "responses" lists contain more than one element, "response_pairing" tells FindingFive how to combine stimuli and responses across trials.
  • Possible values: "alternate", "partitioned", "random". See the following tabs for details on each of these.
  • Default: "alternate".
  • Responses are always evenly distributed among the stimuli - that is, if a trial template contains N times as many stimuli as responses, each response will be associated with exactly N stimuli
  • The number of stimuli must be an exact multiple of the number of responses.
  • The pattern as specified by "stimulus_pattern" is applied after response pairing - that is, FindingFive pairs stimuli and responses together according to the specified "response_pairing" first, and then applies the specified "stimulus_pattern".

"alternate" pairs the first response (r1) with the first stimulus (s1), the second response (r2) with the second stimulus (s2), the third response (r3) with the third stimulus (s3), and so on, until all responses are used, at which point FindingFive goes back to the beginning of the response list and continues to pair the responses with the remaining stimuli in the same pattern.

1
2
3
4
5
6
7
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2", "s3", "s4", "s5", "s6"],
  "responses": ["r1", "r2", "r3"],
  "response_pairing": "alternate" // this is the default
  //and can be omitted
}
In the above example, r1 will be paired with s1 and s4, r2 with s2 and s5, r3 with s3 and s6.

"partitioned" evenly divides the entire list of stimuli into sublists according to the number of responses. For example, if there are 9 stimuli and 3 responses, the stimuli will be partitioned into 3 sublists of 3. Then, preserving the original order of the stimulus list, "partitioned" pairs the first response with the stimuli in the first sublist, the second response with the stimuli in the second sublist, and so on until all responses are used.

1
2
3
4
5
6
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2", "s3", "s4", "s5", "s6"],
  "responses": ["r1", "r2", "r3"],
  "response_pairing": "partitioned"
}
In the above example, the list of 6 stimuli will be divided into subsets of 2, because there are 3 responses. r1 will be paired with s1 and s2, r2 with s3 and s4, r3 with s5 and s6.

"random" randomly pairs each response with stimuli. If there are more stimuli than responses, multiple stimuli will be assigned to each response. For example, if there are 9 stimuli and 3 responses, FindingFive will create 9 trials for which each response is randomly paired with 3 stimuli, without overlap.

1
2
3
4
5
6
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2", "s3", "s4", "s5", "s6"],
  "responses": ["r1", "r2", "r3"],
  "response_pairing": "random"
}
In the above example, each response will be randomly paired with 2 stimuli, displaying each stimulus only once. For example, r1 might be paired with s4 and s5, r2 with s2 and s6, r3 with s1 and s3.

follow_up_responses

  • Definition: One or more responses to conditionally display depending on how a participant has responded to a previous question (defined in the "responses" of this trial template).
  • Possible values: Dictionary including the name of the previous response, the values of this response to match, and the name of the follow-up response. Multiple follow-up conditions can be used (see example).

1
2
3
4
5
6
"follow_up_responses": {"previous_choice_response": [
    // follow-up condition #1
    {"match": ["value1", "value2"], "responses": ["follow_up_response1"]},
    // follow-up condition #2
    {"match": "value3", "responses": ["follow_up_response2", "audio_response"]}
]}
The above snippet tells FindingFive to display a response named "follow_up_response1" if the participant chooses either value1 or value2 in the "previous_choice_response" (which must be defined in "responses" of this trial template), and display two other different responses if the participant chooses value3 instead.

response_confirm

  • Definition: If set to true, participants will need to explicitly confirm their responses before proceeding to the next trial. Default (or omission) is false, in which case the study will proceed to the next trial immediately after all responses on the current trial have been recorded.
  • Possible values: true or false
  • Default: false

1
2
3
4
5
6
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2", "s3"],
  "responses": ["r1", "r2", "r3"],
  "response_confirm": true
}
The above snippet requires participants to confirm their responses on each trial before advancing to the next.

1
2
3
4
5
6
7
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2", "s3"],
  "responses": ["r1", "r2", "r3"],
  "response_confirm": false // this is the default
  // and can be omitted
}
Here, participants will automatically advance to the next trial upon providing a response.

Timing Properties

delay

  • Definition: Delay the onset of a trial. This is particularly useful for implementing an inter-trial interval.
  • Possible values: A number of seconds (fractions are supported)

1
2
3
4
5
6
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2", "s3"],
  "responses": ["r1", "r2", "r3"],
  "delay": 1.6
}
The above code introduces a delay of 1600 milliseconds before each trial.

duration

  • Definition: The amount of time to wait before automatically proceeding to the next trial. This is useful in cases where no responses are needed (such as during a training phase). This feature should not be used on trials where participant resposnes are needed. To turn off automatic advancement to the next trial, see “auto_advance”.
  • Possible values: A number of seconds (fractions are supported)

1
2
3
4
5
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2", "s3"],
  "duration": 1.6
}
In the above example, participants will passively view each stimulus for 1600 milliseconds before automatically advancing to the next trial.

countdown_visible

  • Definition: If set to true and "duration" is greater than 0, then a timer will appear on each trial to remind participants explicitly that this is a timed trial.
  • Possible values: true or false
  • Default: false

1
2
3
4
5
6
7
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2", "s3"],
  "responses": ["r1", "r2", "r3"],
  "duration": 3,
  "countdown_visible": true
}
In this example, on each trial, participants will see a timer count down three seconds before advancing to the next trial (regardless of whether they provide a response or not).

Trial Progression Properties

auto_advance

  • Definition: If set to true, participants will automatically advance to the next trial when stimuli with barrier finish on the current trial. When set to false, a continue button will appear for participants to click on to advance to the next trial.
  • Possible values: true or false
  • Default: When "duration" is longer than 0, the default is true; otherwise, false.

1
2
3
4
5
6
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2", "s3"],
  "duration": 1.6,
  "auto_advance": false
}
In the above example, participants will not automatically advance to the next trial after 1600 milliseconds but will be required to click a continue button to advance to the next trial.

1
2
3
4
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2", "s3"]
}
In the second example, since "duration" is not specified, "auto_advance" will be set to false'. Participants will be required to click a continue button to advance to the next trial.

continue_button

  • Definition: Whether or not a continue button is displayed and when it appears. By default, FindingFive automatically determines if a trial will have a continue button and when that continue button appears, which should produce the desired behavior for most cases.
  • Possible values: see the display and onset sub-properties below.

"display"

  • Definition: Whether to always display the continue button or to allow FindingFive to automatically determine if it is displayed.
  • Possible values: "auto" or "always"
  • Default: "auto"

1
2
3
4
5
6
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2", "s3"],
  "responses": ["r1", "r2", "r3"],
  "continue_button": {"display": "auto", "onset": "auto"}
}
In this example, FindingFive will automatically determine whether or not to display a continue button for each trial.

1
2
3
4
5
6
7
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2", "s3"],
  "responses": ["r1", "r2", "r3"],
  "continue_button": {"display": "always", "onset":
                      "immediate"}
}
In this example, FindingFive will always display a continue button, which will be visible from the onset of each trial.

"onset"

  • Definition: Whether to display the continue button from the beginning of the trial or to allow FindingFive to automatically determine when it is displayed.
  • Possible values: "auto" or "immediate"
  • Default: "auto"

1
2
3
4
5
6
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2", "s3"],
  "responses": ["r1", "r2", "r3"],
  "continue_button": {"display": "auto", "onset": "auto"}
}
In this example, FindingFive will automatically determine whether (and when) a continue button should be displayed for each trial.

1
2
3
4
5
6
7
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2", "s3"],
  "responses": ["r1", "r2", "r3"],
  "continue_button": {"display": "always", "onset":
                      "immediate"}
}
In this example, FindingFive will always display a continue button, which will be visible from the onset of each trial.

Data Submission Properties

submission_point

  • Definition: If set to false, then data collected on trials generated from this template will not be submitted to the server right away. Instead, it will be cached and waiting to be submitted until the next trial that doesn’t have this setting. Setting this property to false is recommended for reaction-time-critical trials to avoid network latencies.
  • Possible values: true or false
  • Default: true, meaning that data collected on a trial will be submitted at the end of the trial by default.
1
2
3
4
5
6
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2", "s3"],
  "responses": ["r1", "r2", "r3"],
  "submission_point": false
}

Display Properties

vertical_center

  • Definition: If set to true, stimuli and responses on this trial will be displayed from the very top of the screen; normally, FindingFive vertically centers all content.
  • Possible values: true or false
  • Default: false
1
2
3
4
5
6
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2", "s3"],
  "responses": ["r1", "r2", "r3"],
  "vertical_center": true
}

Misc Properties

replayable

  • Definition: If set to true, a clickable banner saying “replay this trial” will appear on the top left corner of all trials generated from this trial template. Participants can refresh a trial by clicking that banner. When multiple questions are displayed on a trial, this allows participants who have not yet submitted an answer to the final question to change their responses.
  • Possible values: true or false
  • Default: false

1
2
3
4
5
6
"T1": {
  "type": "basic",
  "stimuli": ["s1", "s2", "s3"],
  "responses": [["r1", "r2", "r3"]],
  "replayable": true
}
In this example, participants are given the option to replay trials by clicking a banner. When a participant replays a trial, they reset all responses (e.g., r1, r2, and r3) and must provide them again.