Time-Varying Parameters
When doing modeling work, the researcher may want to simulate interventions or events that vary over time. In (our 2021 paper)[https://academic.oup.com/jid/article/223/6/1019/6122459], we simulated the effects of COVID-19–Related behavior change and clinical service interruption on HIV and STI incidence. These included simulations with systemic events with a beginning and an end. To work with these situations, EpiModel offers an optional module to programmatically handle parameter changes across time steps.
This vignette assumes a basic understanding of EpiModel custom models. If the code does not make sense, please check the EpiModel Tutorials.
Parameter Updaters
To define what parameters should change and when during the simulation, we need to define updaters. An updater is a list with to named elements: at, the time step when the change will take place, and param a named list of parameters to update.
list(
at = 10,
param = list(
inf.prob = 0.3,
act.rate = 0.5
)
)This example defines an updater that will change the value of the inf.prob parameter to 0.3 and the value to the act.rate parameter to 0.5. This change will happen during the 10th time step.
As mentioned above, we usually want to define several changes at once. EpiModel accept a list of updaters.
# Create a `list.of.updaters`
list.of.updaters <- list(
# this is one updater
list(
at = 100,
param = list(
inf.prob = 0.3,
act.rate = 0.3
)
),
# this is another updater
list(
at = 125,
param = list(
inf.prob = 0.01
)
)
)
# The `list.of.updaters` goes into `param.net` under `param.updater.list`
param <- param.net(
inf.prob = 0.1,
act.rate = 0.1,
param.updater.list = list.of.updaters
)In this example, we define 2 updaters, one that occurs at time step 100 and the other one at time step 20. In practice, inf.prob and act.rate are set to 0.1 at the beginning by param.net, at time step 100 they are both updated to 0.3 and at time step 125 act.rate is reduced to 0.01.
Enabling the updater Module
This functionality is part of an optional module provided by EpiModel, updater.net. This module must then be enabled in control.net.
Below we set up a complete example with a closed population SI model using the parameters and updaters defined above. We then plot the size of the infected and susceptible population over time to see the effects of the updaters.
control <- control.net(
type = NULL, # must be NULL as we use a custom module
nsims = 1,
nsteps = 200,
verbose = FALSE,
updater.FUN = updater.net,
infection.FUN = infection.net
)
nw <- network_initialize(n = 50)
nw <- set_vertex_attribute(nw, "race", rbinom(50, 1, 0.5))
est <- netest(
nw,
formation = ~edges,
target.stats = 25,
coef.diss = dissolution_coefs(~offset(edges), 10, 0),
verbose = FALSE
)
#> Starting maximum pseudolikelihood estimation (MPLE):
#> Evaluating the predictor and response matrix.
#> Maximizing the pseudolikelihood.
#> Finished MPLE.
#> Stopping at the initial estimate.
init <- init.net(i.num = 10)
mod <- netsim(est, param, init, control)
#>
#> A MESSAGE occured in module 'updater.FUN' at step 100
#>
#>
#> At timestep = 100 the following parameters where modified:
#> 'inf.prob', 'act.rate'
#>
#> A MESSAGE occured in module 'updater.FUN' at step 125
#>
#>
#> At timestep = 125 the following parameters where modified:
#> 'inf.prob'
plot(mod)
This is the minimal example to simplify the demonstration of these time-varying parameters.
Important: when enabling the updater.net module, the researcher must pay particular attention to the order the modules are run. It is recommended to have the updater.net module run first so the changes happen at the beginning of the time step.
Some functionality of updater.net were not described above and are explained in ?EpiModel::updater.net.
Verbosity
When creating an updater, one can add an optional verbose element to the list. If TRUE, updater.net will output a message describing what changes where performed when it occurs during the simulation.
#> $at
#> [1] 10
#>
#> $param
#> $param$inf.prob
#> [1] 0.3
#>
#> $param$act.rate
#> [1] 0.5
#>
#>
#> $verbose
#> [1] TRUERelative Parameter Changes
It is sometime useful to configure the changes with respect to the current value instead of a fixed new value. This is possible, as demonstrated below.
#> $at
#> [1] 10
#>
#> $param
#> $param$inf.prob
#> function(x) plogis(qlogis(x) + log(2))
#>
#> $param$act.rate
#> [1] 0.5This updater will set the value of act.rate to 0.5 as we saw earlier. But, for inf.prob we put a function (not a function call). In this case, updater.net will apply the function to the current value of act.rate. If we consider as in the previous example that act.rate is set to 0.1 by param.net, then its new value will be obtained by adding an Odds Ratio of 2 to the original value plogis(qlogis(0.1) + log(2)): 0.1818182.