¶ Overview
The notion of "blocks" in FindingFive's Study Grammar intuitively matches the concept of "blocks of trials" as commonly understood in experimental psychology. Here we describe the most versatile and commonly used block, the Basic Block. You can also find the Branching Block and the Exit Block on subsequent pages.
¶ Basic Form
Similar to the trial template, a block is defined by a property-value pair under the "Procedure" section of the FindingFive Study Editor.
Its key serves as the name of the block, which can be referenced in other parts of the procedure. Its value is another dictionary that tells FindingFive which trial templates to present in the block and the presentation pattern of the block.
¶ Required Properties
¶ trial_templates
- Definition: A list containing the names of trial templates used in the block. You can use the same trial template multiple times in this list; each instance of the trial template will create trials independently from the other ones.
- Possible values: The trial templates mentioned in the list must be first defined as an existing trial template.
There can be as many blocks as needed in an experiment, but the maximum number of trials in a single block is currently set at 150 to ensure an optimal participant experience.
"block_A": {
"trial_templates": ["training_trials", "test_trials", "training_trials"],
// other properties of the block omitted
}
¶ pattern
Definition: A dictionary that specifies how the trial templates in this block are mixed and sequenced together. The dictionary usually consists of two properties: "order" and "repeat", such as:
{"order": SOME_ORDER, "repeat": NUMBER_OF_REPEATS}
A quick note: Interactions between the “pattern” of a block and the “stimulus_pattern” of a trial template are hierarchically organized. For instance, consider a block with two trial templates (A and B), each of which will generate 5 actual trials. The block has a “pattern” of {"order": "alternate"}, while both trial templates are set to use a “stimulus_pattern” of {"order": "random"}.
The net effect of this configuration is that, in the resulting block, trials will alternate between those of Template A and those of Template B, as in ABABABABAB. At the same time, if you ignore all the B trials, the stimuli in A trials are randomized. Similarly, if you ignore A trials, stimuli in B trials are randomized as well.
¶ order
- Definition: the order in which the trial templates are presented
- Possible values:
"fixed","randomized_templates","randomized_trials","alternate","alternate_random","pseudorandomized_template_traversal". Please see the following tabs for details on each order. - Default:
"fixed".
"fixed" presents each trial template in the order specified in "trial_templates". For example:
"block_A": {
"trial_templates": ["training_trials", "test_trials", "training_trials"],
"pattern": {"order": "fixed"} // you can also omit this line since this is the default pattern
}
In this setup, all trials created from the trial template "training_trials" will be presented first (subject to the stimulus pattern, followed by trials created from "test_trials", and then by those from "training_trials" again. Note that the two sets of trials created from the two instances of "training_trials" are completely independent.
"randomized_templates" presents each trial template specified in "trial_templates" completely (like "fixed"), but in a randomized order. For example:
"block_A": {
"trial_templates": ["training_trials_A", "training_trials_B"],
"pattern": {"order": "randomized_templates"}
}
In this setup, all the "A" training trials are presented together, and so are the "B" training trials. However, which trial template gets selected first is random. As a result, some participants will see A trials before B and others B before A.
"randomized_trials" presents one trial from a randomly selected trial template at a time, but leaves the stimulus pattern within each trial template intact. This order can be thought of as sampling the trials from a randomly selected template until all trials have been exhausted from all templates. Note that this is a true randomization order, where all templates have an equal chance of being selected at any time, regardless of what the previous template is.
"block_A": {
"trial_templates": ["training_trials_A", "training_trials_B"],
"pattern": {"order": "randomized_trials"}
}
The above example differs from "randomized_templates" in that the A training trials and B training trials will now be mixed together in an entirely randomly manner. In other words, "randomized_trials" mixes trials across templates, while "randomized_templates" reoorders templates themselves.
"alternate" presents one trial from each template at a time, sequentially alternating between all trial templates. This order also leaves the stimulus pattern within each trial template intact. It can be thought of as “yoking” trials together from multiple templates and presenting them as groups of “yoked” trials.
"alternate_random" first does the same “trial yoking” as the "alternate" pattern, but then performs randomization on the yoked groups of trials. This can be quite helpful in experimental designs where individual stimuli are presented across multiple trials in a set (e.g., mask, prime, target, fixation). See our tutorial: Randomizing trials that are paired across trial templates.
"pseudorandomized_template_traversal" presents one trial from a randomly selected trial template at a time, subject to the constraint that templates of the same name are never presented consecutively. Since this order “traverses” the available templates, it requires the number of trials generated by each trial template to be exactly the same.
"block_A": {
"trial_templates": ["training_trials_A", "training_trials_B", "training_trials_C"],
"pattern": {"order": "pseudorandomized_template_traversal"}
}
In the above example, training trials A will never be followed by A itself. When there are only two trial templates in a block, this is effectively the same as "alternate_random", but the speed at which this order operates is much slower. As a result, we recommend using "pseudorandomized_template_traversal" only when there are 3 or more trial templates in a block.
¶ repeat
- Definition: the total number of times that all trial templates will be cycled through. For each cycle, the trials are always independently created from the trial templates. That is, if any randomization-based pattern is used at the trial template level or at the block level, any subsequent repetition always applies the randomization methods from scratch. Participants will not see the same trial order in a repetition.
- Possible values: an integer greater than or equal to 1
- Default: 1
The following example demonstrates one quick way to present a total of 4 sets of training trials, two for A and another two for B. Importantly, the training trials for the same type (A or B) will have different orders due to randomization is applied from scratch in each repetition.
"block_A": {
"trial_templates": ["training_trials_A", "training_trials_B"],
"pattern": {"order": "fixed", "repeat": 2}
}
¶ Optional Properties
¶ catch_trials
Definition: a list of dictionaries, each of which specifies a trial template to be inserted in this block as catch trials. If more than one catch trial applies to the same trial template (see “after” below), they will be applied in order. Each dictionary must have the following form:
{"template": NAME_OF_TEMPLATE, "frequency": K, "after": [], "cycle_through": false}
¶ template
- Definition: the name of a trial template from which catch trials are created.
- Possible values: the name of any trial template defined in the experiment.
Catch trials are created in the same way as regular trials from the definitions of trial templates.
¶ frequency
- Definition: the frequency at which the catch trials appear in a study, defined as one catch trial every K number of non-catch trials.
- Possible values: an integer smaller than the total number of non-catch trials
¶ after
- Definition: a list of names of trial template after which the catch trial(s) should be inserted. By default, catch trials will be inserted after any trial, as long as the frequency condition is met. Specifying the "after" property allows one to insert catch trials after only trials created from a subset of trial templates in this block.
- Possible values: a list of trial template names that are used in this block.
- Default value:
[](i.e., an empty list, indicating no specific restrictions on trial templates)
¶ cycle_through
- Definition: when there are more slots to insert catch trials than the number of catch trials (that will be generated) in this block, whether FindingFive should cycle through the catch trials created from the catch trial templates. The most common usage for setting this to true is when one needs to insert the same catch trial over and over again.
- Possible values:
trueorfalse - Default value:
false(that is, once all catch trials have appeared, the rest of the block will have no catch trials)
For example, {"template": "TS1", "frequency": 5} will result in a block of trials where trials created from TS1, with its own stimulus pattern, will appear after every 5 trials (that is, 5 non-catch trials would appear between catch trials). These trials are intended to provide a periodic “check” on participants throughout a block (e.g., by checking a participant’s attention with an N-back task, or asking whether the participant understands the instructions at various points throughout the task).
¶ cover_trials
- Definition: a list of trial templates to be presented at the beginning of the entire block. This is often useful for presenting one-time instructions or other introductory materials.
"blocks": {
"BL1": {
"trial_templates": ["TSA", "TSB"],
"cover_trials": ["BlockIntro"],
"pattern": {"order": "randomized_trials", "repeat": 2}
}
}
In this example, trials from the "BlockIntro" template will be presented first to start the block, and then trials from the templates "TSA" and "TSB" will be presented twice, each time using between-template randomization method "randomized_trials".
¶ end_trials
- Definition: a list of trial templates to be presented at the end of the entire block. This is often useful for presenting one-time debrief information at the end of an experiment or block.
"blocks": {
"BL1": {
"trial_templates": ["TSA", "TSB"],
"pattern": {"order": "randomized_trials", "repeat": 2},
"end_trials": ["BlockEnd"]
}
}
In this example, trials from the templates "TSA" and "TSB" will be presented twice, each time using between-template randomization method "randomized_trials". Afterwards, the "BlockEnd" trial template is presented to conclude the block.
¶ fetching_point
- Definition: Turns on or off incremental fetching at the end of this block.
- Possible values:
- If set to
true, FindingFive will load all blocks defined in the"block_sequence"of the procedure, up till this block; - If set to
false, then the next block(s) in the "block_sequence" of the procedure, up till the next fetching point or the end of the study, will be loaded.
- If set to
- Default:
false
The advantage to turning on fetching points is to split the loading of a potentially gigantic study into multiple parts, thus making the initial loading much faster. However, it does increase network-related failure points - i.e., at each incremental loading point, there’s always a chance for participants' Internet connection to experience a hiccup. The default behavior of a FindingFive study is loading all blocks of trials at the beginning of a study (which will result in a relatively long loading time for studies with more than 500 trials).