The current major release of EpiModel,
EpiModel 2.0, incorporates several substantial changes to the core EpiModel workflow compared to previous version of EpiModel. These changes were to add new functionality to EpiModel, streamlining dynamic infectious disease models. This tutorial document reviews the major changes to EpiModel, details the new features that have been added, and provides examples migration of code from EpiModel 1.x to EpiModel 2.0.
Throughout this document,
R code blocks have been commented with the relevant EpiModel version:
## EpiModel 1.x refers to code used in previous versions of EpiModel and
## EpiModel 2.0 refers to code from the current version of EpiModel. Uncommented code remains unchanged between versions of EpiModel. Note that all of these substantial changes were made to the network class of models, which is the core innovative modeling class in EpiModel.
Broader information on EpiModel may be found by visiting EpiModel on Github.
In this section, we detail the core functionality that remains in EpiModel 2.0 but that were revised for efficiency, flexibility, and user accessibility. Changes in this section will be further demonstrated in the “EpiModel 1.x Code Migration” section below.
In EpiModel 1.x, the built-in network models featured both one-mode and two-mode default parameterizations. The two-model parameterization allowed for easy modeling of heterogeneous populations in which there were epidemic parameters specific to a subgroup. One significant change to the EpiModel workflow is in how we handle heterogeneous subpopulations in the built-in (core) epidemic models for networks. In the EpiModel 1.x workflow, designation of a subpopulation was done by initializing a new network and setting its
bipartite input parameter equal to the number of vertices in the first mode:
## EpiModel 1.x num1 <- num2 <- 50 nw <- network.initialize(num1 + num2, directed = FALSE, bipartite = num1)
This creates a network in which there are 50 vertices in mode one and 50 vertices in mode two. By defining this as a bipartite network, no mixing within modes occurs. A prime example of bipartite networks is modeling purely heterosexual networks, in which the modes correspond to sexes and there is only mixing across that attribute. Bipartite networks are more often defined as nodes in each mode being of distinct classes. Examples include persons (in mode 1) and places (in mode 2); persons may be linked to places but places cannot be linked to places.
However, the built-in models are framed as one-mode networks (one class of persons), even with certain mixing constraints. Therefore, in EpiModel 2.0 we move away from defining our networks as bipartite and instead refer to heterogeneous sub-populations as groups. This requires a change in networks are parameterized, with nodal attributes now.
## EpiModel 2.0 num1 <- num2 <- 50 nw <- network_initialize(n = num1 + num2) nw <- set_vertex_attribute(nw, "group", rep(1:2, c(num1, num2)))
Above is the updated syntax for creating “two-group” networks within the EpiModel 2.0 workflow. The network is initialized as usual using
network_initialize (a new EpiModel-specific version of
network.initialize detailed in section “Network Initialization Functions” below). Then to capture the previous dissortative mixing structure, we create a vertex attribute,
set_vertex_initialize (a new EpiModel-specific version of
This change allows for consistency in interpretation of nodes as well as greater flexibility of network model parameterization. In a two-group network defined above, with group assignment handled with a vertex attribute, it is now possible to model a continuum of mixing conditions, from purely dissortative (mirroring bipartite networks) to random mixing to purely assortative mixing. For example, in a heterosexual mixing model in a population of males and females, this new workflow allows us to model dissortative mixing with a
nodematch term within the ERGM formula with an associated target statistic of 0:
## EpiModel 2.0 num1 <- num2 <- 50 nw <- network_initialize(n = num1 + num2) nw <- set_vertex_attribute(nw, "group", rep(1:2, c(num1, num2))) formation <- ~edges + nodematch("group") target.stats <- c(30, 0)
We could also change the parameterization such that some same-sex relationships are possible, but fewer than expected by chance alone:
target.stats <- c(30, 3)
The vertex attribute
group now takes on a special class within built-in EpiModel models. Users should be mindful when constructing networks in which
group is a vertex attribute and note whether or not the interpretation of “group” membership aligns with that detailed above. Further, the
group vertex attribute is restricted to levels of 1 and 2; other combinations of attribute levels – say, 0 and 1 or “male” and “female” – are not permitted here and may result in unintended results.
With two-group network models specified in this way, one can feed in group-specific epidemic parameters and initial conditions. For example, here are these inputs for a two-group SIR model in an open population (in which there are births and deaths):
param <- param.net(inf.prob = 0.3, inf.prob.g2 = 0.15, rec.rate = 0.02, rec.rate.g2 = 0.02, a.rate = 0.002, a.rate.g2 = NA, ds.rate = 0.001, ds.rate.g2 = 0.001, di.rate = 0.001, di.rate.g2 = 0.001, dr.rate = 0.001, dr.rate.g2 = 0.001) init <- init.net(i.num = 10, i.num.g2 = 10, r.num = 0, r.num.g2 = 0)
The parameters and initial conditions that pertain to the second group (those with a group attribute value of 2), correspond with the arguments ending with
Note that these two-group network models with the group attribute were possible before, in EpiModel 1.x, it is just that now the group attribute in the network object has a specific and special meaning when running the epidemic models with
netsim. For clarity, we have limited these to two groups within the built-in models, but the functionality may be easily extended with the network model extensions (described at the bottom of this document and in other tutorials).
The group attribute may be on the network object and that attribute may also be referenced within an ERGM formation model. This approach would be used when one wants to have a two-group epidemic model (with group-specific epidemic model parameters) and also a network structure that incorporates heterogeneity in activity or mixing by group. But one may also have an epidemic model in which the group attribute is on the network object but not in the ERGM formation model. This would be used in the case when one wants to have group-specific epidemic model parameters but no network structure specific to groups.