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,
group, using set_vertex_initialize (a new
EpiModel-specific version of set.vertex.attribute).
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 .g2.
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.