Scenario Structure

Let's take a closer look at our physical activity example in the scenarios page,

{
    "subject": "activity",
    "algorithms": ["MPoRTv2-PUMF"],
    "description": "Canadian Physical Activity Guidelines for Adults (18-64 years)",
    "scenarios": [
        {
            "name": "total attribution",
            "male": {
                "variables": [
                    {
                        "variableName": "PACDEE",
                        "method": "attribution",
                        "targetPop": [0, 2.1],
                        "postScenarioRange": [2.1, null],
                        "scenarioValue": 2.1
                    }
                ]
            },
            "female": {
                "variables": [
                    {
                        "variableName": "PACDEE",
                        "method": "attribution",
                        "targetPop": [0, 2.1],
                        "postScenarioRange": [2.1, null],
                        "scenarioValue": 2.1
                    }
                ]
            }
        }
}

In the following sections we will go over the each of the variables described in the JSON object.

subject: string

Describes the risk factors the scenarios will operate on. Used only for documentation/metadata purposes.

algorithms: string[]

Describes the algorithms the scenarios are compatible with. Currently only used for documentation/metadata purposes.

description: string

More details on the scenarios. Used only for documentation/metadata purposes.

scenarios: object[]

An array of objects where each entry describes a scenario. Although the example above has only one object, the scenarios array can have as many objects as makes sense for this collection of scenarios. Note that each object represents a scenario and should describe only those variables that pertain to that scenario.

scenarios[scenarioIndex].name: string

The name of this scenario. Used only for documentation/metadata purposes.

scenarios[scenarioIndex].male: object, scenarios[index].female: object

Each scenario object should contain 2 fields, male and female, each of which describes the scenario for the corresponding sex. Both objects can be the same or different, depending on the scenario.

scenarios[scenarioIndex].sex.variables: object[]

The variables that will be manipulated for this sex for this scenario. The fields in each object will vary depending on the method used. However a lot of the fields will not change. These common fields will be documented here. For method specific fields refer to the documentation for the different method types.

scenarios[scenarioIndex].sex.variables[variableIndex].variableName: string

The name of the variable to manipulate. This field should match with a variable from the model running the scenario. For eg. the variableName PACDEE is present in our MPoRTv2-PUMF model.

scenarios[scenarioIndex].sex.variables[variableIndex].targetPop: [null | number, null | number]

Inclusion criteria for this scenario. Here a value of null refers to -Infinity or +Infinity depending on it's position in the array. In our example object, a targetPop value of [0, 2.1] was used to imply to only include people whose PACDEE variable has a value between 0 and 2.1 inclusive. Note that the value of the targetPop field is always in reference to the variable defined in the variableName field. More examples are given below:

• [null, null]: Include everybody
• [null, 0]: Include only people with negative values of PACDEE

scenarios[scenarioIndex].sex.variables[variableIndex].postScenarioRange: [null | number, null | number]

Used to limit the value of the variable after it has been updated. Just like the targetPop field, null refers to -Infinity or +Infinity depending on it's position in the array. In the physical activity object above, a postScenarioRange of [2.1, null] will make sure the variable after manipulation will be between the given range. For eg. if the variable value after manipulation was 1, it would be brought up to the lower limit of 2.1

scenarios[scenarioIndex].sex.variables[variableIndex].method: string

How the variable will be manipulated. Take a look at the various methods we support under the scenario section.

scenarios[scenarioIndex].sex.variables[variableIndex].scenarioValue: number

The main value that will be used to update the variable. The meaning of this value will change depending on the method field. For eg., an attribution method with a scenario value of 7 will update the variable value to 7 where as a relative-scenario method with a scenario value of 7 will increase the variable value by 7%.

Next Steps

Take a look at the various method types we support TODO

Or take a look at our examples section that goes over some scenarios that we use at Project Big Life TODO