This vignette discusses mechanisms usable inside
EpiModel network models with custom modules. More
information about these in the Extending
EpiModel section of the Network Modeling for
Epidemics course materials.
Inside the simulation, the networks themselves are stored under
dat$run$nw. Ultimately this vignette will describe multiple
aspects of working with network objects.
The cumulative edgelist refers to the historical list of edges in a network with the time step they start and stopped. Such a list allows to query current relationships (contacts, partnerships, etc.) as well as past ones.
The creation and update of the cumulative edgelist is done through
the EpiModel::update_cumulative_edgelist function.
dat <- update_cumulative_edgelist(dat, network, truncate = Inf)
This function takes 3 arguments:
dat: the Main List Object.network: the number of the network for which to create
the cumulative edgelist (for multi-layer network simulations).truncate: a number of time steps after which an
inactive edge should be removed from the cumulative edgelist (this saves
computer memory for large-scale simulations).The function returns a modified version of dat that
needs to be assigned back.
The following snippet will update the cumulative edgelist for all the networks used by a model and remove the edges that ended more than 100 steps ago.
for (n_network in seq_along(dat$run$nw)) {
dat <- update_cumulative_edgelist(dat, n_network, truncate = 100)
}
In a complete model, this code would need to be run at the end of the initialization module and at each time-step after the resimulation of the networks.
Cumulative edge-list refers to nodes with their Unique Ids. See
help("unique_id-tools", package = "EpiModel") for more
information.
Accessing the cumulative edge-list of a given network is done using
the EpiModel::get_cumulative_edgelist function.
el_cuml <- get_cumulative_edgelist(dat, network)
The returned el_cuml object is a tibble with four
columns:
head: the unique_id first node of the
edge.tail: the unique_id second node of the
edge.start: the time-step where the edge was created.stop: the last time-step the edge was active.EpiModel::get_cumulative_edgelist will
always return a tibble with this 4
columns, even if the cumulative edgelist has not been calculated for
this particular network or if no edges are present. In these cases, the
tibble will
have no rows but keep the correct column structure.
The stop column will always contain
NA if an edge is currently active.
Once an edge is not present anymore, the stop column for
this edge will contains the last step the edge was active. This means
that an edge with a stop value existed from
start to stop both inclusive. This makes it
coherent with how R treats the indexes in a vector for
instance (from 1 to length(vector) inclusive).
We often want to get the cumulative edgelist over several networks as
one. EpiModel::get_cumulative_edgelists_df function provide
such functionality.
el_cumls <- get_cumulative_edgelists_df(dat, networks = NULL)
The networks argument can be a vector of network
position or NULL. In this latter case, all networks will be
selected.
The output of this function is similar to
EpiModel::get_cumulative_edgelist with the addition of a
network column, indicating for each edge the networks it
exists on.
A typical use of the cumulative edgelist is the trace the contacts of
a node over given number of steps. The
EpiModel::get_partners function simplifies this
process:
partner_list <- get_partners(
dat,
index_posit_ids,
networks = NULL,
truncate = Inf,
only.active.nodes = FALSE
)
Here we call “indexes” the nodes whose partners (contacts) we want to extract. The arguments are:
dat: as in
get_cumulative_edgelists_df.index_posit_ids: a list of positional Ids for the
indexes of interest.networks: as in
get_cumulative_edgelists_df.truncate: similar to the truncate argument
to update_cumulative_edgelist this argument filter out
partnerships over this age.only.active.nodes: if set to TRUE,
partnership with inactive nodes are removed.The output is similar to get_cumulative_edgelists_df but
the first two columns are called index and
partner and contains the Unique Ids of the indexes given in
argument in the first column and there partners in the second one.
Note that the we refer to the indexes of interest with their
Positional Ids but the index and partners
columns contains Unique Ids as they can refer to nodes no longer in the
network.