Skip to content

Basic Block

The concept of "blocks" in FindingFive's Study Grammar aligns intuitively with the idea of "blocks of trials" as commonly understood in experimental psychology. Below, we describe the Basic Block, which is used in most experimental setups. You may also need the Branching Block and the Exit Block in more complex study designs.

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, as shown in the example here:

A sample definition of blocks
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "type": "blocking",
  "blocks": {
    "block_1": {
      "trial_templates": ["trial_group_1"]
    },
    "block_2": {
      "trial_templates": ["trial_group_2"]
    }
  },
  "block_sequence": ["block_1", "block_2"]
}

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.

    Limit on the number of trials per block

    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 250 to ensure an optimal participant experience.

    To override this limit, see max_trials.

1
2
3
4
"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:

1
2
3
4
"block_A": {
  "trial_templates": ["training_trials", "test_trials", "training_trials"],
  "pattern": {"order": SOME_ORDER, "repeat": NUMBER_OF_REPEATS}
}
A Quick Note on Hierarchical Patterns

The interaction between the pattern of a block and the stimulus_pattern of a trial template is hierarchically organized. For example, consider a block with two trial templates (A and B), each generating 5 trials. The block has a "pattern" set to {"order": "alternate"}, while both trial templates use a "stimulus_pattern" of {"order": "random"}.

In this configuration:

  • The resulting block alternates between trials from Template A and Template B, producing a sequence like ABABABABAB.
  • Within the trials of Template A, the stimuli are randomized. Similarly, within the trials of Template B, the stimuli are also randomized.

This hierarchical structure ensures that the block-level alternation is preserved, while the stimulus-level randomization operates independently within each trial template.

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: 

1
2
3
4
"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:

1
2
3
4
"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.

1
2
3
4
"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.

1
2
3
4
"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.

1
2
3
4
"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 into 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. For example:

1
2
3
4
5
6
7
8
"block_A": {
  "trial_templates": ["training_trials_A", "training_trials_B"],
  "catch_trials": [
    {"template": NAME_OF_TEMPLATE_1, "frequency": K, "after": [], "cycle_through": false},
    {"template": NAME_OF_TEMPLATE_2, "frequency": L, "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.

    Note

    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: true or false
  • 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.
1
2
3
4
5
6
7
"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.

1
2
3
4
5
6
7
"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.

  • Default: false

    Understanding Fetching Points

    Setting fetching_point to true allows the loading of a study to be split into multiple parts, significantly reducing the initial wait time. However, this approach introduces the risk of network-related failure points: at each incremental loading point, there is a risk of interruptions due to participants' internet connectivity issues.

    By default, a FindingFive study loads all blocks of trials at the start of the study. While this ensures a seamless experience once loaded, it can result in longer initial loading times, particularly for studies with more than 500 trials.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
"blocks": {
        "BL1": {
          "trial_templates": ["TSA", "TSB"],
          "fetching_point": true
        }
        "BL2": {
          "trial_templates": ["TSC", "TSD"],
        }
},
"block_sequence": ["BL1", "BL2"]

In this example, the experiment will only load the trials of Block BL1 initially and then the trials of BL2 only when the participant has reached the end of BL1. Without the fetching point setting, trials of both BL1 and BL2 will be loaded at the beginning of an experiment.

max_trials

  • Definition: Specifies the maximum number of trials allowed in a block.
  • Possible values: A positive integer (e.g., 250).
  • Default: 250
1
2
3
4
5
6
"blocks": {
        "BL1": {
          "trial_templates": ["TSA", "TSB", "TSC", "TSD"],
          "max_trials": 300 // this overrides the default limit, 250 trials per block
        }
}