Procedures

A procedure defines the manner in which Trial templates are presented in a study. Properties of a procedure are defined inside the top-level property procedure in a study specification.

Basic form

The procedure of a study is defined in the following form:

"procedure": {
  "type": "NAME_OF_PROCEDURE",
  "PROCEDURE_SPECIFIC_PROPERTY1": SOME_VALUE
  "PROCEDURE_SPECIFIC_PROPERTY2": SOME_VALUE
  ...
}

For example, we can define a simple blocking procedure with the following code:

"procedure": {
  "type": "blocking",
  "blocks": {
        "BL1": {
          "trial_templates": ["TSA", "TSB"],
          "pattern": {"order": "random", "repeat": 2},
          "end_trials": ["BlockEnd"]
        },
        "BL2": {
          "trial_templates": ["TS2", "TS3", "ATS1", "CommentTS"],
          "pattern": {"order": "fixed", "repeat": 1},
          "catch_trial": {"template": "CatchTS", "frequency": 3}
        }
  },
  "block_sequence": ["BL1", "BL2"]
}

Here, we use the procedure type blocking, with two blocks named BL1 and BL2. In BL1, two trial templates will be presented, in a random order so that realized trials of TSA and TSB are randomly mixed together. In addition, each of the realizable trials of those two templates will be presented twice (the effect of "repeat": 2). Finally, the BL1 block ends with a trial template BlockEnd, which presumably displays some instructional text.

The properties in BL2 have similar interpretations. A main difference in BL2 is that the trial templates will be presented in the order listed under the trial_templates property (in this example, ["TS2", "TS3", "ATS1", "CommentTS"]). In addition, participants will experience a “catch trial” (most likely unknown to them) drawn from the trial template CatchTS every 3 normal trials (that is, for every 4 trials, the last trial is a catch trial).

Note

Unlike other top-level properties:

  • The procedure keyword is singular. This is due to the current limitation that only a single procedure can be specified for any study
  • Procedures do not have names, since they don’t need to referenced in other parts of the specification
  • Procedure-specific properties (such as "blocks" in the above example) are listed directly in the top-level property procedure.

Built-in procedure types

blocking

The most common procedure in which trials are organized into one or more blocks. To use blocking, specify "blocking" for the "type" property of the top-level property "procedure":

"procedure": {
   "type": "blocking",
}

Procedure-specific properties

blocks

A dictionary of property-value pairs, each corresponding to the definition of a block. The order in which block definitions are listed here is inconsequential. The presentation order of individual blocks during a study is determined by block_sequence instead.

block_sequence

A list consisting of block names, participant group dictionaries, or a combination of both that defines the order in which individual blocks are presented in a study, possibly varying across participant groups.

  • list of block names: When the "block_sequence" is a list of only block names, all participants will experience these blocks in sequence. For example, if we define the procedure as:

    "procedure": {
        "type": "blocking",
        "blocks": {
           "block_1": {
               // block_1 definition here
           },
           "block_2": {
               // block_2 definition here
           }
        },
        "block_sequence": ["block_2", "block_1"]
    }
    

    "block_2" will be presented before "block_1" for all participants.

  • list of participant group dictionaries: When the "block_sequence" is a list of participant group dictionaries, participants of each group will experience their own sequence of blocks as specified by the researcher. For example, if we define the procedure as:

    "procedure": {
        "type": "blocking",
        "blocks": {
           "block_1": {
               // block_1 definition here
           },
           "block_2": {
               // block_2 definition here
           }
        },
        "block_sequence": [{"GroupA": ["block_1", "block_2"], "GroupB": ["block_1"]}]
    }
    

    Then, during a session of this study, half of all participants will be assigned to “GroupA”, who will be presented first "block_1" and then "block_2". The other half of participants will be assigned to “GroupB”, who will be presented only "block_1". The assignment of participants to different groups is automatically handled by FindingFive. Researchers only need to make sure that the number of participants requested for a session is a multiple of the number of participant groups defined here.

  • list of a mixture of block names and participant group dictionaries: When the "block_sequence" is a list consisting of a mixture of block names and participant group dictionaries, blocks outside participant group dictionaries will be presented to all participants, and each participant group will experience their own sequence of blocks as specified in the dictionaries. For example, given the following definition:

    "procedure": {
        "type": "blocking",
        "blocks": {
              // block defintions here
        },
        "block_sequence": [
                 "block_1",
                 {"GroupA": ["block_2"], "GroupB": ["block_3"]},
                 "block_4"
        ]
    }
    

    During a session of this study, half of all participants will be assigned to “GroupA”, who will be presented "block_1", "block_2", and then "block_4". The other half of participants will be assigned to “GroupB”, who will be presented "block_1", "block_3", and then "block_4". In other words, researchers only need to define participant groups for the part of a study that actually differs among groups.

Definition of a block

A block is defined by a property-value pair inside the property blocks when a blocking procedure is used. Its key serves as the name of the block, which can be referenced in other parts of the procedure. Its value defines the trial templates and the presentation pattern of that block.

Properties:
  • trial_templates - a list consisting of the names of trial templates used in the block
  • pattern - a dictionary with two properties: "order" can be either "fixed" (present the trial templates in the order specified in "trial_templates"), "random" (randomly mix the trial templates), and "alternate" (present one trial from each template); "repeat" takes an integer, which specifies the total number of times that each trial template will be used.

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 of Template A and those of B will alternate, 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.

All interactions follow this rule (e.g., setting both patterns to random will mix everything together).

  • catch_trial - a dictionary of the form {"template": NAME_OF_TEMPLATE, "frequency": SOME_INTEGER} used to specify the name of the catch trial template, and the frequency at which it appears in a study (defined as every X number of non-catch trials). For example, {"template": "TS1", "frequency": 5} will result in a block of trials where trials realized 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 (optional) - additionally specify a list of trial templates that will be used as the beginning trials of the entire block
  • end_trials (optional) - additionally specify a list of trial templates that will be used as the ending trials of the entire block

For example, the following snippet from the above example defines a block:

"BL2": {
   "trial_templates": ["TS2", "TS3", "ATS1", "CommentTS"],
   "pattern": {"order": "fixed", "repeat": 1},
   "catch_trial": {"template": "CatchTS", "frequency": 3}
}