Scenario Structure

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

{
  "subject": "Activity",
  "algorithms": ["MPoRTv2-PUMF"],
  "description": "Physical activity - MET-hours per day",
  "scenarios": [
    {
      "name": "Canadian physical activity guidelines",
      "method": "Attribution",
      "reference": "Canadian 24-Hour Movement Guidelines: An Integration of Physical Activity, Sedentary Behaviour, and Sleep. Canadian Society for Exercise Physiology website: https://www.csep.ca/guidelines. Accessed November 22, 2019",
      "description": "the Canadian Physical Activity Guidelines for Adults (18+ years) of 150 minutes of moderate- to vigorous-intensity activity per week, translated into daily MET-hours.",
      "descriptionDetails": "Respondents below the reference value are recoded to reference value (2.1 MET-hours/day), all other respondents retain their reported value. Respondents with missing values are assumed to have the population average prior to changing their exposure.",
      "male": {
        "variables": [
          {
            "variableName": "PACDEE",
            "method": "attribution-scenario",
            "scenarioValue": 2.1,
            "targetPop": [0, 2.1],
            "postScenarioRange": [2.1, null]
          }
        ]
      },
      "female": {
        "variables": [
          {
            "variableName": "PACDEE",
            "method": "attribution-scenario",
            "scenarioValue": 2.1,
            "targetPop": [0, 2.1],
            "postScenarioRange": [2.1, null]
          }
        ]
      }
    }
  ]
}

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. This text will be displayed under the Name column in the Interventions scenario table in the app.

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].reference: string

A reference for this scenario. Used only for documentation/metadata purposes.

scenarios[scenarioIndex].description: string

A high level description for this scenario. Used only for documentation/metadata purposes.

scenarios[scenarioIndex].descriptionDetails: string

A detailed description for 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

To find a list of the various method types we support, check out the sidebar.

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