knitr::opts_chunk$set( collapse = TRUE, comment = "#>" )
library(EpiModel)
This vignette discusses mechanisms usable inside EpiModel
network models with custom modules. More information about these in the "New Network Models with
EpiModel" section of the EpiModel tutorials.
Inside the simulation, the networks themselves are stored under dat[["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[["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.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.