Skip to content

Branching Block

FindingFive Study Grammar can handle conditional branching - presenting different blocks of trials depending on the responses that participants have provided on previous trials. The participant responses to be evaluated for conditional branching must all reside in the same "branching block", which is described in detail on this page.

A branching block is just like a basic block in terms of its core functionality: organizing and presenting trials. The "magic" is that the responses collected on trials in a branching block can be used to determine what additional blocks that a participant will see afterwards.

Info

Conditional branching operates at the block level. There is a different mechanism for conditionally presenting responses within a trial. See follow-up responses for details.

Required Properties

Info

All properties of a basic block are also applicable to a branching block. This page only lists properties that are specific to a branching block.

branching

Definition: A dictionary specifying the branching instructions, consisting of the following properties:

"method"

  • Definition: the branching method.
  • Possible values: "accuracy" or "match".

To set up a branching block that branches based on the accuracy of a response, the very first step is to specify the "method" as "accuracy".

1
2
3
4
5
6
7
"BranchingBlock": {
    // define trial templates and other properties here
    "branching": {
         "method": "accuracy"
         // incomplete example: read other properties to see what else must be specified
    }
}

To set up a branching block that branches based on whether participant responses match predefined values, the very first step is to specify the "method" as "match".

1
2
3
4
5
6
7
"BranchingBlock": {
    // define trial templates and other properties here
    "branching": {
         "method": "match"
         // incomplete example: read other properties to see what else must be specified
    }
}

"triggers"

  • Definition: a list of dictionaries specifying which responses should be used for branching evaluation.
  • Possible values: each dictionary must be of the form
1
2
3
4
{
  "trial_template": "trial_template_name",
  "response": "response_name"
}

Continuing the accuracy-based branching example introduced in "method", we can specify the triggers as follows:

1
2
3
4
5
6
7
8
"BB_Accuracy": {
    // define trial templates and other properties here
    "branching": {
         "triggers": [{"trial_template": "my_trial_template",
                      "response": "my_choice_response"}]
         // incomplete example; read other properties to see what else must be specified
    }
}
In this example, the branching decision will be based on the participant responses collected by the "my_choice_response" responses on "my_trial_template" trials. The trial template referenced (here, "my_trial_template") must exist in the branching block, and the response referenced (here, "my_choice_response") must exist within the referenced trial template.

Warning

When "method" is "accuracy", the trigger response(s) must have a defined "target" so that the correctness of participant responses can be determined.

"min_score" (accuracy-only)

  • Definition: the minimum accuracy when "method" is "accuracy". This property is required only when the method of a branching block is "accuracy".
  • Possible values: Any decimal number between 0 and 1.

The follow example illustrates a setup where the branching threshold is set at 80% - that is, participants who achieve an accuracy of at least 80% on trigger responses will see a different branch of upcoming blocks than those who do not.

1
2
3
4
5
6
7
8
"BB_Accuracy": {
    // define trial templates and other properties here
    "branching": {
         "method": "accuracy",
         "min_score": 0.8,
         // incomplete example; read other properties to see what else must be specified
    }
}

"branches"

  • Definition: a dictionary for defining the branching outcomes as a function of participant responses. The keys of the dictionary reference branch names and the values correspond to target response values.

Info

Branch names referenced here need to be defined in the block sequence. See the linked page for details on how to define branches, and how branches and participant groups can be combined to form powerful randomized designs.

  • Possible values: depends on whether "method" is "accuracy" or "match"; see Example Code sections for details.

When method is "accuracy", only two branches can be referenced and must be in the form of

1
{"success_branch_name": true, "fail_branch_name": false}

The branch name that corresponds to true indicates the branch to take when participants’ accuracy is at least "min_score", and the branch name that corresponds to false indicates the branch to take when accuracy is lower than "min_score".

Here's a (more) complete example of a branching block using the accuracy method:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
"BB_Accuracy": {
    // define trial templates and other properties here
    "branching": {
         "method": "accuracy",
         "triggers": [{"trial_template": "my_trial_template",
                      "response": "my_choice_response"}],
         "min_score": 0.8,
         "branches": {"A": true, "B": false}
    }
}

By setting up this branching block, participants who achieve 80% or higher accuracy on "my_choice_response" will see blocks defined in branch "A", while others will see blocks defined in branch "B".

When method is "match", two or more branches can be referenced in the form of

1
2
3
4
5
6
{
  "branch_1": ["response_value1", ..., "response_valueN"],
  "branch_2": [...],
  ...,
  "default_branch": null
}
Similar to the case of "accuracy", the keys are the names of the branches to take. The values are lists of target response values. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
"BB_Match": {
    // define trial templates and other properties here
    "branching": {
         "method": "match",
         "triggers": [{"trial_template": "some_trial",
                       "response": "some_choice_response"},
                      {"trial_template": "other_trial",
                       "response": "some_rating_response"}],
         "branches": {"A": ["left button", 4],
                      "B": ["right button", 5],
                      "C": null}
    }
}

This setup directs participants who clicked the "left button" of "some_choice_response" on "some_trial" and gave a rating of 4 for the "some_rating_response" on "other_trial" to Branch "A". If the combo of responses happened to be ["right button", 5] then those participants will see Branch "B". For all other participants whose responses did not fall under either scenario, they will skip the branching action and continue directly onto whatever comes after the branching.

It's important to note that in defining the length of each response value list in "branches" here must match the number of triggers. If participant responses match the target response outcomes, then the corresponding branch will be taken for the participant. If participant respones match none of the target response outcomes, the default branch (whose value is null) will be taken.

"iterations" (accuracy-only)

  • Definition: (optional) when method is "accuracy", iterations is a dictionary of the following form, which enables iterative training of participants on the same block of trials:

1
{"min": MINIMUM_ITERATIONS, "max": MAXIMUM_ITERATIONS, "eval_all": false}
* Possible values: - "min" takes an integer number that specifies the minimum iterations of training (defaults to 1); - "max" takes an integer that specifies the maximum iterations of training (also defaults to 1); - "eval_all" takes a boolean value (true or false) that specifies whether training accuracy should be evaluated on all iterations (true) or only the last iteration (false, which is the default).

We can add iterative training to an accuracy-based branching block by adding the "iterations" property:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
"BB_Accuracy": {
    // define trial templates and other properties here
    "branching": {
         "method": "accuracy",
         "triggers": [{"trial_template": "my_trial_template",
                      "response": "my_choice_response"}],
         "min_score": 0.8,
         "branches": {"A": true, "B": false},
         "iterations": {"max": 3}
    }
}
As a result of this setup, participants will be given a max of 3 chances to achieve an accuracy of 80% to pass this block. For those who fail to reach the 80% accuracy at the end of all 3 iterations, they will be directed to the "B" branch. All other participants will see the "A" branch instead.