Specifying time-varying parameter modifications
This section describes how to specify modifications to any of the parameters of the transmission model or observational model during certain time periods.
Modifiers are a powerful feature in flepiMoP to enable users to modify any of the parameters being specified in the model during particular time periods. They can be used, for example, to mirror public health control interventions, like non-pharmaceutical interventions (NPIs) or increased access to diagnosis or care, or annual seasonal variations in disease parameters. Modifiers can act on any of the transmission model parameters or observation model parameters.
In the seir_modifiers
and outcome_modifiers
sections of the configuration file the user can specify several possible types of modifiers which will then be implemented in the model. Each modifier changes a parameter during one or multiple time periods and for one or multiple specified subpopulations.
We currently support the following intervention types. Each of these is described in detail below:
"SinglePeriodModifier"
– Modifies a parameter during a single time period"MultiPeriodModifier"
– Modifies a parameter by the same amount during a multiple time periods"ModifierModifier"
– Modifies another intervention during a single time period"StackedModifier"
– Combines two or more interventions additively or multiplicatively, and is used to be able to turn on and off groups of interventions easily for different runs.
Note that if you want a parameter to vary continuously over time (for example, a daily transmission rate that is influenced by temperature and humidity), then it is easier to do this by using a "timeseries" parameter value than by combining many separate modifiers. Timeseries parameter values are described in the seir::parameters section. Timeseries parameters foroutcomes
parameters (e.g., a testing rate that fluctuates rapidly due to test availability) are in development but not currently available.
Within flepiMoP, modifiers can be run as "scenarios". With scenarios, we can use the same configuration file to run multiple versions of the model where only the modifiers applied differ.
The modifiers
section contains two sub-sections: modifiers::scenarios
, which lists the name of the modifiers that will run in each separate scenario, and modifiers::modifiers
, where the details of each modifier are specified (e.g., the parameter it acts on, the time it is active, and the subpopulation it is applied to). An example is outlined below
In this example, each scenario runs a single intervention, but more complicated examples are possible.
The major benefit of specifying both "scenarios" and "modifiers" is that the user can use "StackedModifier"
option to combine other modifiers in different ways, and then run either the individual or combined modifiers as scenarios. This way, each scenario may consist of one or more individual parameter modifications, and each modification may be part of multiple scenarios. This provides a shorthand to quickly consider multiple different versions of a model that have different combinations of parameter modifications occurring. For example, during an outbreak we could evaluate the impact of school closures, case isolation, and masking, or any one or two of these three measures. An example of a configuration file combining modifiers to create new scenarios is given below
The seir_modifiers::scenarios
andoutcome_modifiers::scenarios
sections are optional. If the scenarios
section is not included, the model will run with all of the modifiers turned "on".
If thescenarios
section is included for either seir
or outcomes
, then each time a configuration file is run, the user much specify which modifier scenarios will be run. If not specified, the model will be run one time for each combination of seir
and outcome
scenario.
Example
[Give a configuration file that tries to use all the possible option available. Based on simple SIR model with parameters beta
and gamma
in 2 subpopulations. Maybe a SinglePeriodModifier on beta
for a lockdown and gamma
for isolation, one having a fixed value and one from a distribution, MultiPeriodModifier for school year in different places, ModifierModifer for ..., StackedModifier for .... ]
modifiers::scenarios
modifiers::scenarios
A optional list consisting of a subset of the modifiers that are described in modifiers::settings
, each of which will be run as a separate scenario. For example
or
modifiers::settings
modifiers::settings
A formatted list consisting of the description of each modifier, including its name, the parameter it acts on, the duration and amount of the change to that parameter, and the subset of subpopulations in which the parameter modification takes place. The list items are summarized in the table below and detailed in the sections below.
Config item | Required | Type/format | Description |
---|---|---|---|
| required | string | one of |
| required | string | The parameter on which the modification is acting. Must be a parameter defined in |
| required | numeric, YYYY-MM-DD | The date when the modification starts. Notation depends on value of |
| required | numeric, YYYY-MM-DD | The date when the modification ends. Notation depends on value of |
| required | String, or list of strings | The subpopulations to which the modifications will be applied, or |
| required | Distribution, or single value | The relative amount by which a modification reduces the value of a parameter. |
| optional | string or a list of lists of strings | A list of lists defining groupings of subpopulations, which defines how modification values should be shared between them, or |
| Used only for | String | Name of the original modification which will be further modified |
| Used only for | List of strings | List of modifier names to be grouped into the new combined modifier/scenario name |
SinglePeriodModifier
SinglePeriodModifier
interventions enable the user to specify a multiplicative reduction to a parameter
of interest. It take a parameter
, and reduces it's value by value
(new = (1-value
) * old) for the subpopulations listed insubpop
during the time interval [period_start_date
, period_end_date
]
For example, if you would like to create an SEIR modifier called lockdown
that reduces transmission by 70% in the state of California and the District of Columbia between two dates, you could specify this with a SinglePeriodModifier, as in the example below
Example
Or to create an outcome variable modifier called enhanced_testing during which the case detection rate doubles
Configuration options
method
: SinglePeriodModifier
parameter
: The name of the parameter that will be modified. This could be a parameter defined for the transmission model in seir::parameters
or for the observational model in outcomes
. If the parameter is used in multiple transitions in the model then all those transitions will be modified by this amount.
period_start_date
: The date when the modification starts, in YYYY-MM-DD format. The modification will only reduce the value of the parameter after (inclusive of) this date.
period_end_date
: The date when the modification ends, in YYYY-MM-DD format. The modification will only reduce the value of the parameter before (inclusive of) this date.
subpop:
A list of subpopulation names/ids in which the specified modification will be applied. This can be a single subpop
, a list, or the word "all"
(specifying the modification applies to all existing subpopulations in the model). The modification will do nothing for any subpopulations not listed here.
value:
The fractional reduction of the parameter during the time period the modification is active. This can be a scalar number, or a distribution using the notation described in the Distributions section. The new parameter value will be
subpop_groups:
An optional list of lists specifying which subsets of subpopulations in subpop should share parameter values; when parameters are drawn from a distribution or fit to data. See subpop_groups
section below for more details.
MultiPeriodModifier
MultiPeriodModifier
interventions enable the user to specify a multiplicative reduction to the parameter
of interest by value
(new = (1-value
) * old) for the subpopulations listed in subpop
during multiple different time intervals each defined by a start_date
and end_date.
For example, if you would like to describe the impact that transmission in schools has on overall disease spread, you could create a modifier that increases transmission by 30% during the dates that K-12 schools are in session in different regions (e.g., Massachusetts and Florida):
Example
Configuration options
method: MultiPeriodModifier
parameter
: The name of the parameter that will be modified. This could be a parameter defined for the transmission model in seir::parameters
or for the observational model in outcomes
. If the parameter is used in multiple transitions in the model then all those transitions will be modified by this amount.
groups:
A list of subpopulations (subpops
) or groups of them, and time periods the modification will be active in each of them
groups:subpop
A list of subpopulation names/ids in which the specified modification will be applied. This can be a singlesubpop
, a list, or the word"all" (
specifying the modification applies to all existing subpopulations in the model). The modification will do nothing for any subpopulations not listed here.groups: periods
A list of time periods, each defined by a start and end date, when the modification will be appliedgroups:periods:start_date
The date when the modification starts, in YYYY-MM-DD format. The modification will only reduce the value of the parameter after (inclusive of) this date.groups:periods:end_date
The date when the modification ends, in YYYY-MM-DD format. The modification will only reduce the value of the parameter before (inclusive of) this date.
value:
The fractional reduction of the parameter during the time period the modification is active. This can be a scalar number, or a distribution using the notation described in the Distributions section. The new parameter value will be
subpop_groups:
An optional list of lists specifying which subsets of subpopulations in subpop should share parameter values; when parameters are drawn from a distribution or fit to data. See subpop_groups
section below for more details.
ModifierModifier
ModifierModifier
interventions allow the user to specify an intervention that acts to modify the value of another intervention, as opposed to modifying a baseline parameter value. The intervention multiplicatively reduces the modifier
of interest by value
(new = (1-value
) * old) for the subpopulations listed in subpop
during the time interval [period_start_date
, period_end_date
].
Example
For example, ModifierModifier
could be used to describe a social distancing policy that is in effect between two dates and reduces transmission by 60% if followed by the whole population, but part way through this period, adherence to the policy drops to only 50% of in one of the subpopulations population:
Note that this configuration is identical to the following alternative specification
However, there are situations when the ModiferModifier
notation is more convenient, especially when doing parameter fitting.
Configuration options
method: ModifierModifier
baseline_modifier:
The name of the original parameter modification which will be further modified.
parameter
: The name of the parameter in the baseline_scenario
that will be modified.
period_start_date
: The date when the intervention modifier starts, in YYYY-MM-DD format. The intervention modifier will only reduce the value of the other intervention after (inclusive of) this date.
period_end_date
: The date when the intervention modifier ends, in YYYY-MM-DD format. The intervention modifier will only reduce the value of the other intervention before (inclusive of) this date.
subpop:
A list of subpopulation names/ids in which the specified intervention modifier will be applied. This can be a single subpop
, a list, or the word "all"
(specifying the interventions applies to all existing subpopulations in the model). The intervention will do nothing for any subpopulations not listed here.
value:
The fractional reduction of the baseline intervention during the time period the modifier intervention is active. This can be a scalar number, or a distribution using the notation described in the Distributions section. The new parameter value will be
and so the value of the underlying parameter that was modified by the baseline intervention will be
subpop_groups:
An optional list of lists specifying which subsets of subpopulations in subpop should share parameter values; when parameters are drawn from a distribution or fit to data. See subpop_groups
section below for more details.
StackedModifier
Combine two or more modifiers into a scenario, so that they can easily be singled out to be run together without the other modifiers. If multiply modifiers act during the same time period in the same subpopulation, their effects are combined multiplicatively. Modifiers of different types (i.e. SinglePeriodModifier, MultiPeriodModifier, ModifierModifier, other StackedModifiers) can be combined.
Examples
or
Configuration options
method
: StackedModifier
modifiers
: A list of names of the other modifiers (specified above) that will be combined to create the new modifier (which we typically refer to as a "scenario")
modifiers::modifiers::groups
subpop_groups:
For any of the modifier types, subpop_groups
is an optional list of lists specifying which subsets of subpopulations in subpop
should share parameter values; when parameters are drawn from a distribution or fit to data. All other subpopulations not listed will have unique intervention values unlinked to other areas. If the value is 'all',
then all subpopulations will be assumed to have the same modifier value. When the subpop_groups
option is not specified, all subpopulations will be assumed to have unique values of the modifier.
For example, for a model of disease spread in Canada where we want to specify that the (to be varied) value of a modification to the transmission rate should be the same in all the Atlantic provinces (Nova Scotia, Newfoundland, Prince Edward Island, and New Brunswick), the same in all the prairie provinces (Manitoba, Saskatchewan, Alberta), the same in the three territories (Nunavut, Northwest Territories, and Yukon), and yet take unique values in Ontario, Quebec, and British Columbia, we could write
Last updated