Package 'EpiModel'

Description

Details

The EpiModel software package provides tools for building, solving, and visualizing mathematical models of infectious disease dynamics. These tools allow users to simulate epidemic models in multiple frameworks for both pedagogical purposes ("base models") and novel research purposes ("extension models").

Model Classes and Infectious Disease Types

EpiModel provides functionality for three classes of epidemic models:

• Deterministic Compartmental Models: these continuous-time models are solved using ordinary differential equations. EpiModel allows for easy specification of sensitivity analyses to compare multiple scenarios of the same model across different parameter values.

• Stochastic Individual Contact Models: a novel class of individual-based, microsimulation models that were developed to add random variation in all components of the transmission system, from infection to recovery to vital dynamics (arrivals and departures).

• Stochastic Network Models: with the underlying statistical framework of temporal exponential random graph models (ERGMs) recently developed in the Statnet suite of software in R, network models over epidemics simulate edge (e.g., partnership) formation and dissolution stochastically according to a specified statistical model, with disease spread across that network.

EpiModel supports three infectious disease types to be run across all of the three classes.

• Susceptible-Infectious (SI): a two-state disease in which there is life-long infection without recovery. HIV/AIDS is one example, although for this case it is common to model infection stages as separate compartments.

• Susceptible-Infectious-Recovered (SIR): a three-stage disease in which one has life-long recovery with immunity after infection. Measles is one example, but modern models for the disease also require consideration of vaccination patterns in the population.

• Susceptible-Infectious-Susceptible (SIS): a two-stage disease in which one may transition back and forth from the susceptible to infected states throughout life. Examples include bacterial sexually transmitted diseases like gonorrhea.

These basic disease types may be extended in any arbitrarily complex way to simulate specific diseases for research questions.

Model Parameterization and Simulation

EpiModel uses three model setup functions for each model class to input the necessary parameters, initial conditions, and control settings:

• param.dcm, param.icm, and param.net are used to input epidemic parameters for each of the three model classes. Parameters include the rate of contacts or acts between actors, the probability of transmission per contact, and recovery and demographic rates for models that include those transitions.

• init.dcm, init.icm, and init.net are used to input the initial conditions for each class. The main conditions are limited to the numbers or, if applicable, the specific agents in the population who are infected or recovered at the simulation outset.

• control.dcm, control.icm, and control.net are used to specify the remaining control settings for each simulation. The core controls for base model types include the disease type, number of time steps, and number of simulations. Controls are also used to input new model functions (for DCMs) and new model modules (for ICMs and network models) to allow the user to simulate fully original epidemic models in EpiModel. See the documentation for the specific control functions help pages.

With the models parameterized, the functions for simulating epidemic models are:

• dcm for deterministic compartmental models.

• icm for individual contact models.

• Network models are simulated in a three-step process:

  1. netest estimates the statistical model for the network structure itself (i.e., how partnerships form and dissolve over time given the parameterization of those processes). This function is a wrapper around the ergm and tergm functions in the ergm and tergm packages. The current statistical framework for model simulation is called "egocentric inference": target statistics summarizing these formation and dissolution processes collected from an egocentric sample of the population.

  2. netdx runs diagnostics on the dynamic model fit by simulating the base network over time to ensure the model fits the targets for formation and dissolution.

  3. netsim simulates the stochastic network epidemic models, with a given network model fit in netest. Here the function requires this model fit object along with the parameters, initial conditions, and control settings as defined above.

Author(s)

Maintainer: Samuel Jenness [email protected]

Authors:

• Steven M. Goodreau [email protected]

• Martina Morris [email protected]

• Adrien Le Guillou [email protected]

• Chad Klumb [email protected]

Other contributors:

• Skye Bender-deMoll [email protected] [contributor]

References

The EpiModel website is at https://www.epimodel.org/, and the source code is at https://github.com/EpiModel/EpiModel. Bug reports and feature requests are welcome.

Our primary methods paper on EpiModel is published in the Journal of Statistical Software. If you use EpiModel for any research or teaching purposes, please cite this reference:

Jenness SM, Goodreau SM, and Morris M. EpiModel: An R Package for Mathematical Modeling of Infectious Disease over Networks. Journal of Statistical Software. 2018; 84(8): 1-47. doi:10.18637/jss.v084.i08.

We have also developed two extension packages for modeling specific disease dynamics. For HIV and bacterial sexually transmitted infections, we have developed EpiModelHIV, which is available on Github at https://github.com/EpiModel/EpiModelHIV. For COVID-19, we have developed EpiModelCOVID, which is available at https://github.com/EpiModel/EpiModelCOVID.

See Also

Useful links:

• https://www.epimodel.org/

• https://epimodel.github.io/EpiModel/

• Report bugs at https://github.com/EpiModel/EpiModel/issues/

Description

This function performs a simple operation of updating the edgelist attribute n that tracks the total network size implicit in an edgelist representation of the network.

Usage

add_vertices(el, nv)

Arguments

Details

This function is used in EpiModel modules to add vertices (nodes) to the edgelist object to account for entries into the population (e.g., births and in-migration).

Value

Returns the matrix of current edges, el, with the population size attribute updated based on the number of new vertices specified in nv.

Examples

## Not run: 
library("EpiModel")
nw <- network_initialize(100)
formation <- ~edges
target.stats <- 50
coef.diss <- dissolution_coefs(dissolution = ~offset(edges), duration = 20)
x <- netest(nw, formation, target.stats, coef.diss, verbose = FALSE)

param <- param.net(inf.prob = 0.3)
init <- init.net(i.num = 10)
control <- control.net(type = "SI", nsteps = 100, nsims = 5,
                       tergmLite = TRUE)

# networkLite representation after initialization
dat <- crosscheck.net(x, param, init, control)
dat <- initialize.net(x, param, init, control)

# Check current network size
attributes(dat$el[[1]])$n

# Add 10 vertices
dat$el[[1]] <- add_vertices(dat$el[[1]], 10)

# Check new network size
attributes(dat$el[[1]])$n

## End(Not run)

Description

Apportions a vector of values given a specified frequency distribution of those values such that the length of the output is robust to rounding and other instabilities.

Usage

apportion_lr(vector.length, values, proportions, shuffled = FALSE)

Arguments

Value

A vector of length vector.length containing the apportioned values from values.

Examples

## Not run: 
## Example 1: Without rounding
apportioned_vec_1 <- apportion_lr(4, c(1, 2, 3, 4, 5),
                                     c(0.25, 0, 0.25, 0.25, 0.25))

## Example 2: With rounding
apportioned_vec_2 <- apportion_lr(5, c(1, 2, 3, 4, 5),
                                     c(0.21, 0, 0.29, 0.25, 0.25))

## End(Not run)

Description

Arrive New Nodes to the netsim_dat Object

Usage

arrive_nodes(dat, nArrivals)

Arguments

Details

nArrivals new nodes are added to the network data stored on the netsim_dat object. If tergmLite is FALSE, these nodes are activated from the current timestep onward. Attributes for the new nodes must be set separately.

Note that this function only supports arriving new nodes; returning to an active state nodes that were previously active in the network is not supported.

Value

the updated netsim_dat object with nArrivals new nodes added

Description

Convert an object to a cumulative_edgelist

Usage

as_cumulative_edgelist(x)

Arguments

Details

The edges are active from time start to time stop included. If stop is NA, the edge was not disolved in the simulation that generated the list.

Value

A cumulative_edgelist object, a data.frame with at least the following columns: head, tail, start, stop.

Description

Convert an Edgelist into a Tibble

Usage

as_tibble_edgelist(el)

Arguments

Value

The edgelist in tibble form with two columns named head and tail.

Description

This function extracts a model run from an object of class dcm into a data frame using the generic as.data.frame function.

Usage

## S3 method for class 'dcm'
as.data.frame(x, row.names = NULL, optional = FALSE, run, ...)

Arguments

Details

Model output from dcm simulations are available as a data frame with this helper function. The output data frame will include columns for time, the size of each compartment, the overall population size (the sum of compartment sizes), and the size of each flow.

For models with multiple runs (i.e., varying parameters - see example below), the default with the run parameter not specified will output all runs in a single stacked data frame.

Value

A data frame containing the data from x.

Examples

## Example 1: One-group SIS model with varying act.rate
param <- param.dcm(inf.prob = 0.2, act.rate = seq(0.05, 0.5, 0.05),
                   rec.rate = 1/50)
init <- init.dcm(s.num = 500, i.num = 1)
control <- control.dcm(type = "SIS", nsteps = 10)
mod1 <- dcm(param, init, control)
as.data.frame(mod1)
as.data.frame(mod1, run = 1)
as.data.frame(mod1, run = 10)

## Example 2: Two-group SIR model with vital dynamics
param <- param.dcm(inf.prob = 0.2, inf.prob.g2 = 0.1,
                   act.rate = 3, balance = "g1",
                   rec.rate = 1/50, rec.rate.g2 = 1/50,
                   a.rate = 1/100, a.rate.g2 = NA,
                   ds.rate = 1/100, ds.rate.g2 = 1/100,
                   di.rate = 1/90, di.rate.g2 = 1/90,
                   dr.rate = 1/100, dr.rate.g2 = 1/100)
init <- init.dcm(s.num = 500, i.num = 1, r.num = 0,
                 s.num.g2 = 500, i.num.g2 = 1, r.num.g2 = 0)
control <- control.dcm(type = "SIR", nsteps = 10)
mod2 <- dcm(param, init, control)
as.data.frame(mod2)

Description

This function extracts model simulations for objects of classes icm and netsim into a data frame using the generic as.data.frame function.

Usage

## S3 method for class 'icm'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  out = "vals",
  sim = NULL,
  qval = NULL,
  ...
)

## S3 method for class 'netsim'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  out = "vals",
  sim = NULL,
  ...
)

Arguments

Details

These methods work for both icm and netsim class models. The available output includes time-specific means, standard deviations, quantiles, and simulation values (compartment and flow sizes) from these stochastic model classes. Means, standard deviations, and quantiles are calculated by taking the row summary (i.e., each row of data is corresponds to a time step) across all simulations in the model output.

Value

A data frame containing the data from x.

Examples

## Stochastic ICM SIS model
param <- param.icm(inf.prob = 0.8, act.rate = 2, rec.rate = 0.1)
init <- init.icm(s.num = 500, i.num = 1)
control <- control.icm(type = "SIS", nsteps = 10,
                       nsims = 3, verbose = FALSE)
mod <- icm(param, init, control)

# Default output all simulation runs, default to all in stacked data.frame
as.data.frame(mod)
as.data.frame(mod, sim = 2)

# Time-specific means across simulations
as.data.frame(mod, out = "mean")

# Time-specific standard deviations across simulations
as.data.frame(mod, out = "sd")

# Time-specific quantile values across simulations
as.data.frame(mod, out = "qnt", qval = 0.25)
as.data.frame(mod, out = "qnt", qval = 0.75)

## Not run: 
## Stochastic SI Network Model
nw <- network_initialize(n = 100)
formation <- ~edges
target.stats <- 50
coef.diss <- dissolution_coefs(dissolution = ~offset(edges), duration = 20)
est <- netest(nw, formation, target.stats, coef.diss, verbose = FALSE)

param <- param.net(inf.prob = 0.5)
init <- init.net(i.num = 10)
control <- control.net(type = "SI", nsteps = 10, nsims = 3, verbose = FALSE)
mod <- netsim(est, param, init, control)

# Same data extraction methods as with ICMs
as.data.frame(mod)
as.data.frame(mod, sim = 2)
as.data.frame(mod, out = "mean")
as.data.frame(mod, out = "sd")
as.data.frame(mod, out = "qnt", qval = 0.25)
as.data.frame(mod, out = "qnt", qval = 0.75)

## End(Not run)

Description

This function extracts timed edgelists for objects of class netdx into a data frame using the generic as.data.frame function.

Usage

## S3 method for class 'netdx'
as.data.frame(x, row.names = NULL, optional = FALSE, sim, ...)

Arguments

Value

A data frame containing the data from x.

Examples

# Initialize and parameterize the network model
nw <- network_initialize(n = 100)
formation <- ~edges
target.stats <- 50
coef.diss <- dissolution_coefs(dissolution = ~offset(edges), duration = 20)

# Model estimation
est <- netest(nw, formation, target.stats, coef.diss, verbose = FALSE)

# Simulate the network with netdx
dx <- netdx(est, nsims = 3, nsteps = 10, keep.tedgelist = TRUE,
            verbose = FALSE)

# Extract data from the first simulation
as.data.frame(dx, sim = 1)

# Extract data from all simulations
as.data.frame(dx)

Description

This methods ensures that the data.frame is correctly formatted as an epi.data.frame

Usage

as.epi.data.frame(df)

Arguments

Description

Converts a transmission matrix from the get_transmat function into a network::network class object.

Usage

## S3 method for class 'transmat'
as.network(x, ...)

Arguments

Details

When converting from a transmat to a network object, this functions copies the edge attributes within the transmission matrix ('at', 'infDur', 'transProb', 'actRate', and 'finalProb') into edge attributes on the network.

Value

A network::network object.

Description

Converts a transmission matrix from the get_transmat function into a phylo class object.

Usage

## S3 method for class 'transmat'
as.phylo(x, vertex.exit.times, ...)

Arguments

Details

Converts a transmat object containing information about the history of a simulated infection into a ape::phylo object representation suitable for plotting as a tree with plot.phylo. Each infection event becomes a 'node' (horizontal branch) in the resulting phylo tree, and each network vertex becomes a 'tip' of the tree. The infection events are labeled with the vertex ID of the infector to make it possible to trace the path of infection.

The infection timing information is included to position the phylo-nodes, with the lines to the tips drawn to the max time value +1 (unless vertex.exit.times are passed in it effectively assumes all vertices are active until the end of the simulation).

If the transmat contains multiple infection seeds (there are multiple trees with separate root nodes), this function will return a list of class multiPhylo, each element of which is a phylo object. See read.tree.

Value

A phylo class object.

Examples

set.seed(13)

# Fit a random mixing TERGM with mean degree of 1 and mean edge
# duration of 20 time steps
nw <- network_initialize(n = 100)
formation <- ~edges
target.stats <- 50
coef.diss <- dissolution_coefs(dissolution = ~offset(edges), duration = 20)
est <- netest(nw, formation, target.stats, coef.diss, verbose = FALSE)

# Parameterize the epidemic model as SI with one infected seed
param <- param.net(inf.prob = 0.5)
init <- init.net(i.num = 1)
control <- control.net(type = "SI", nsteps = 40, nsims = 1, verbose = FALSE)

# Simulate the model
mod1 <- netsim(est, param, init, control)

# Extract the transmission matrix
tm <- get_transmat(mod1)
head(tm, 15)

# Convert to phylo object and plot
tmPhylo <- as.phylo.transmat(tm)
par(mar = c(1,1,1,1))
plot(tmPhylo, show.node.label = TRUE,
              root.edge = TRUE,
              cex = 0.75)

Description

Checks for consistency in the implied network statistics of a two-group network in which the group size and group-specific degree distributions are specified.

Usage

check_degdist_bal(num.g1, num.g2, deg.dist.g1, deg.dist.g2)

Arguments

Details

This function outputs the number of nodes of degree 0 to g, where g is the length of a fractional degree distribution vector, given that vector and the size of the group. This utility is used to check for balance in implied degree given that fractional distribution within two-group network simulations, in which the degree-constrained counts must be equal across groups.

Examples

# An unbalanced distribution
check_degdist_bal(num.g1 = 500, num.g2 = 500,
                  deg.dist.g2 = c(0.40, 0.55, 0.03, 0.02),
                  deg.dist.g1 = c(0.48, 0.41, 0.08, 0.03))

# A balanced distribution
check_degdist_bal(num.g1 = 500, num.g2 = 500,
                  deg.dist.g1 = c(0.40, 0.55, 0.04, 0.01),
                  deg.dist.g2 = c(0.48, 0.41, 0.08, 0.03))

Description

Creates a new color-named temporally-extended attribute (TEA) variable in a networkDynamic object containing a disease status TEA in numeric format.

Usage

color_tea(
  nd,
  old.var = "testatus",
  old.sus = "s",
  old.inf = "i",
  old.rec = "r",
  new.var = "ndtvcol",
  new.sus,
  new.inf,
  new.rec,
  verbose = TRUE
)

Arguments

Details

The ndtv package (https://cran.r-project.org/package=ndtv) produces animated visuals for dynamic networks with evolving edge structures and nodal attributes. Nodal attribute dynamics in ndtv movies require a temporally extended attribute (TEA) containing a standard R color for each node at each time step. By default, the EpiModel package uses TEAs to store disease status history in network model simulations run in netsim. But that status TEA is in numeric format (0, 1, 2). The color_tea function transforms those numeric values of that disease status TEA into a TEA with color values in order to visualize status changes in ndtv.

The convention in plot.netsim is to color the susceptible nodes as blue, infected nodes as red, and recovered nodes as green. Alternate colors may be specified using the new.sus, new.inf, and new.rec parameters, respectively.

Using the color_tea function with a netsim object requires that TEAs for disease status be used and that the networkDynamic object be saved in the output: tergmListe must be set to FALSE in control.net.

Value

The updated object of class networkDynamic.

See Also

netsim and the ndtv package documentation.

Description

Plots a compartment flow diagram for deterministic compartmental models, stochastic individual contact models, and stochastic network models.

Usage

comp_plot(x, at, digits, ...)

## S3 method for class 'netsim'
comp_plot(x, at = 1, digits = 3, ...)

## S3 method for class 'icm'
comp_plot(x, at = 1, digits = 3, ...)

## S3 method for class 'dcm'
comp_plot(x, at = 1, digits = 3, run = 1, ...)

Arguments

Details

The comp_plot function provides a visual summary of an epidemic model at a specific time step. The information contained in comp_plot is the same as in the summary functions for a model, but presented graphically as a compartment flow diagram.

For dcm class plots, specify the model run number if the model contains multiple runs, as in a sensitivity analysis. For icm and netsim class plots, the run argument is not used; the plots show the means and standard deviations across simulations at the specified time step.

These plots are currently limited to one-group models for each of the three model classes. That functionality may be expanded in future software releases.

Examples

## Example 1: DCM SIR model with varying act.rate
param <- param.dcm(inf.prob = 0.2, act.rate = 5:7,
                   rec.rate = 1/3, a.rate = 1/90, ds.rate = 1/100,
                   di.rate = 1/35, dr.rate = 1/100)
init <- init.dcm(s.num = 1000, i.num = 1, r.num = 0)
control <- control.dcm(type = "SIR", nsteps = 25, verbose = FALSE)
mod1 <- dcm(param, init, control)
comp_plot(mod1, at = 25, run = 3)

## Example 2: ICM SIR model with 3 simulations
param <- param.icm(inf.prob = 0.2, act.rate = 3, rec.rate = 1/50,
                   a.rate = 1/100, ds.rate = 1/100,
                   di.rate = 1/90, dr.rate = 1/100)
init <- init.icm(s.num = 500, i.num = 1, r.num = 0)
control <- control.icm(type = "SIR", nsteps = 25,
                       nsims = 3, verbose = FALSE)
mod2 <- icm(param, init, control)
comp_plot(mod2, at = 25, digits = 1)

Description

Sets the controls for deterministic compartmental models simulated with dcm.

Usage

control.dcm(
  type,
  nsteps,
  dt = 1,
  odemethod = "rk4",
  dede = FALSE,
  new.mod = NULL,
  sens.param = TRUE,
  print.mod = FALSE,
  verbose = FALSE,
  ...
)

Arguments

Details

control.dcm sets the required control settings for any deterministic compartmental models solved with the dcm function. Controls are required for both base model types and original models. For all base models, the type argument is a necessary parameter and it has no default.

Value

An EpiModel object of class control.dcm.

New Model Functions

The form of the model function for base models may be displayed with the print.mod argument set to TRUE. In this case, the model will not be run. These model forms may be used as templates to write original model functions.

These new models may be input and solved with dcm using the new.mod argument, which requires as input a model function.

See Also

Use param.dcm to specify model parameters and init.dcm to specify the initial conditions. Run the parameterized model with dcm.

Description

Sets the controls for stochastic individual contact models simulated with icm.

Usage

control.icm(
  type,
  nsteps,
  nsims = 1,
  initialize.FUN = initialize.icm,
  infection.FUN = NULL,
  recovery.FUN = NULL,
  departures.FUN = NULL,
  arrivals.FUN = NULL,
  prevalence.FUN = NULL,
  verbose = FALSE,
  verbose.int = 0,
  skip.check = FALSE,
  ...
)

Arguments

Details

control.icm sets the required control settings for any stochastic individual contact model solved with the icm function. Controls are required for both base model types and when passing original process modules. For all base models, the type argument is a necessary parameter and it has no default.

Value

An EpiModel object of class control.icm.

New Modules

Base ICM models use a set of module functions that specify how the individual agents in the population are subjected to infection, recovery, demographics, and other processes. Core modules are those listed in the .FUN arguments. For each module, there is a default function used in the simulation. The default infection module, for example, is contained in the infection.icm function.

For original models, one may substitute replacement module functions for any of the default functions. New modules may be added to the workflow at each time step by passing a module function via the ... argument.

See Also

Use param.icm to specify model parameters and init.icm to specify the initial conditions. Run the parameterized model with icm.

Description

Sets the controls for stochastic network models simulated with netsim.

Usage

control.net(
  type,
  nsteps,
  start = 1,
  nsims = 1,
  ncores = 1,
  resimulate.network = FALSE,
  tergmLite = FALSE,
  cumulative.edgelist = FALSE,
  truncate.el.cuml = 0,
  attr.rules,
  epi.by,
  initialize.FUN = initialize.net,
  resim_nets.FUN = resim_nets,
  summary_nets.FUN = summary_nets,
  infection.FUN = NULL,
  recovery.FUN = NULL,
  departures.FUN = NULL,
  arrivals.FUN = NULL,
  nwupdate.FUN = nwupdate.net,
  prevalence.FUN = prevalence.net,
  verbose.FUN = verbose.net,
  module.order = NULL,
  save.nwstats = TRUE,
  nwstats.formula = "formation",
  save.transmat = TRUE,
  save.network,
  save.run = FALSE,
  save.cumulative.edgelist = FALSE,
  save.other,
  verbose = TRUE,
  verbose.int = 1,
  skip.check = FALSE,
  raw.output = FALSE,
  tergmLite.track.duration = FALSE,
  set.control.ergm = control.simulate.formula(MCMC.burnin = 2e+05),
  set.control.tergm = control.simulate.formula.tergm(MCMC.maxchanges = Inf),
  save.diss.stats = TRUE,
  dat.updates = NULL,
  ...
)

Arguments

Details

control.net sets the required control settings for any network model solved with the netsim function. Controls are required for both base model types and when passing original process modules. For an overview of control settings for base models, consult the Network Modeling for Epidemics course materials For all base models, the type argument is a necessary parameter and it has no default.

Value

An EpiModel object of class control.net.

The attr.rules Argument

The attr.rules parameter is used to specify the rules for how nodal attribute values for incoming nodes should be set. These rules are only necessary for models in which there are incoming nodes (i.e., arrivals). There are three rules available for each attribute value:

• current: new nodes will be assigned this attribute in proportion to the distribution of that attribute among existing nodes at that current time step.

• t1: new nodes will be assigned this attribute in proportion to the distribution of that attribute among nodes at time 1 (that is, the proportions set in the original network for netest).

• Value: all new nodes will be assigned this specific value, with no variation. For example, the rules list attr.rules = list(race = "t1", sex = "current", status = "s") specifies how the race, sex, and status attributes should be set for incoming nodes. By default, the rule is "current" for all attributes except status, in which case it is "s" (that is, all incoming nodes are susceptible).

Checkpointing Simulations

netsim has a built-in checkpoint system to prevent losing computation work if the function is interrupted (SIGINT, power loss, time limit exceeded on a computation cluster). When enabled, each simulation will be saved every .checkpoint.steps time steps. Then, if a checkpoint enabled simulation is launched again with netsim, it will restart at the last checkpoint available in the saved data.

To enable the checkpoint capabilities of netsim, two control arguments have to be set: .checkpoint.steps, which is a positive number of time steps to be run between each file save; and .checkpoint.dir, which is the path to a directory to save the checkpointed data. If .checkpoint.dir directory does not exist, netsim will attempt to create it on the first checkpoint save. With these two controls defined, one can simply re-run netsim with the same arguments to restart a set of simulations that were interrupted.

Simulations are checkpointed individually: for example, if 3 simulations are run on a single core, the first 2 are finished, then the interruption occurs during the third, netsim will only restart the third one from the last checkpoint.

A .checkpoint.compress argument can be set to overwrite the compress argument in saveRDS used to save the checkpointed data. The current default for saveRDS is gunzip (gz), which provides fast compression that usually works well on netsim objects.

By default, if netsim reaches the end of all simulations, the checkpoint data directory and its content are removed before returning the netsim object. The .checkpoint.keep argument can be set to TRUE to prevent this removal to inspect the raw simulation objects.

New Modules

Base network models use a set of module functions that specify how the individual nodes in the network are subjected to infection, recovery, demographics, and other processes. Core modules are those listed in the .FUN arguments. For each module, there is a default function used in the simulation. The default infection module, for example, is contained in the infection.net function.

For original models, one may substitute replacement module functions for any of the default functions. New modules may be added to the workflow at each time step by passing a module function via the ... argument. Consult the Extending EpiModel section of the Network Modeling for Epidemics course materials. One may remove existing modules, such as arrivals.FUN, from the workflow by setting the parameter value for that argument to NULL.

End Horizon

netsim implements an "End Horizon" mechanism, where a set of modules are removed from the simulation at a specific time step. This is enabled through the end.horizon parameter to control.net.

This parameter must receive a list with fields at, the time step at which the end horizon occurs, and modules, a character vector with the names of the modules to remove. (e.g 'list(at = 208, modules = c("arrivals.FUN", "infections.FUN")))

See Also

Use param.net to specify model parameters and init.net to specify the initial conditions. Run the parameterized model with netsim.

Description

This helper function populates a netsim_dat main list object with the minimal required elements. All parameters are optional. When none are given the resulting object is only a shell list of class netsim_dat with the different named elements defined as empty lists.

Usage

create_dat_object(
  param = list(),
  init = list(),
  control = list(),
  run = list()
)

Arguments

Value

A netsim_dat main list object.

Description

An EpiModel scenario allows one or multiple set of parameters to be applied to a model a predefined timesteps. They are usually used by a researcher who wants to model counterfactuals using a pre calibrated model.

Usage

create_scenario_list(scenarios.df)

Arguments

Value

a list of EpiModel scenarios

scenarios.df

The scenarios.df is a data.frame of values to be used as parameters.

It must contain a ".at" column, specifying when the changes should occur. It requires the "updater" module of EpiModel. See, vignette. If the ".at" value of a row is less than two, the changes will be applied to the parameter list iteself. The second mandatory column is ".scenario.id". It is used to distinguish the different scenarios. If multiple rows share the same ".scenario.id", the resulting scenario will contain one updater per row. This permits modifying parameters at multiple points in time. (e.g. an intervention limited in time).

The other column names must correspond either to: the name of one parameter if this parameter is of size 1 or the name of the parameter with "_1", "_2", "N" with the second part being the position of the value for a parameter of size > 1. This means that the parameter names cannot contain any underscore "". (e.g "a.rate", "d.rate_1", "d.rate_2")

Description

Solves deterministic compartmental epidemic models for infectious disease.

Usage

dcm(param, init, control)

Arguments

Details

The dcm function uses the ordinary differential equation solver in the deSolve package to model disease as a deterministic compartmental system. The parameterization for these models follows the standard approach in EpiModel, with epidemic parameters, initial conditions, and control settings.

The dcm function performs modeling of both base model types and original models with new structures. Base model types include one-group and two-group models with disease types for Susceptible-Infected (SI), Susceptible-Infected-Recovered (SIR), and Susceptible-Infected-Susceptible (SIS). Both base and original models require the param, init, and control inputs.

Value

A list of class dcm with the following elements:

• param: the epidemic parameters passed into the model through param, with additional parameters added as necessary.

• control: the control settings passed into the model through control, with additional controls added as necessary.

• epi: a list of data frames, one for each epidemiological output from the model. Outputs for base models always include the size of each compartment, as well as flows in, out of, and between compartments.

References

Soetaert K, Petzoldt T, Setzer W. Solving Differential Equations in R: Package deSolve. Journal of Statistical Software. 2010; 33(9): 1-25. doi:10.18637/jss.v033.i09.

See Also

Extract the model results with as.data.frame.dcm. Summarize the time-specific model results with summary.dcm. Plot the model results with plot.dcm. Plot a compartment flow diagram with comp_plot.

Examples

## Example 1: SI Model (One-Group)
# Set parameters
param <- param.dcm(inf.prob = 0.2, act.rate = 0.25)
init <- init.dcm(s.num = 500, i.num = 1)
control <- control.dcm(type = "SI", nsteps = 500)
mod1 <- dcm(param, init, control)
mod1
plot(mod1)

## Example 2: SIR Model with Vital Dynamics (One-Group)
param <- param.dcm(inf.prob = 0.2, act.rate = 5,
                   rec.rate = 1/3, a.rate = 1/90, ds.rate = 1/100,
                   di.rate = 1/35, dr.rate = 1/100)
init <- init.dcm(s.num = 500, i.num = 1, r.num = 0)
control <- control.dcm(type = "SIR", nsteps = 500)
mod2 <- dcm(param, init, control)
mod2
plot(mod2)

## Example 3: SIS Model with act.rate Sensitivity Parameter
param <- param.dcm(inf.prob = 0.2, act.rate = seq(0.1, 0.5, 0.1),
                   rec.rate = 1/50)
init <- init.dcm(s.num = 500, i.num = 1)
control <- control.dcm(type = "SIS", nsteps = 500)
mod3 <- dcm(param, init, control)
mod3
plot(mod3)

## Example 4: SI Model with Vital Dynamics (Two-Group)
param <- param.dcm(inf.prob = 0.4,  inf.prob.g2 = 0.1,
                   act.rate = 0.25, balance = "g1",
                   a.rate = 1/100, a.rate.g2 = NA,
                   ds.rate = 1/100, ds.rate.g2 = 1/100,
                   di.rate = 1/50, di.rate.g2 = 1/50)
init <- init.dcm(s.num = 500, i.num = 1,
                 s.num.g2 = 500, i.num.g2 = 0)
control <- control.dcm(type = "SI", nsteps = 500)
mod4 <- dcm(param, init, control)
mod4
plot(mod4)

Description

Deduplicate a cumulative edgelist by combining overlapping edges

Usage

dedup_cumulative_edgelist(el)

Arguments

Value

A cumulative edgelist with no overlapping edges

Description

Given a current two-column matrix of edges and a vector of vertex IDs, this function removes any rows of the edgelist in which the IDs are present.

Usage

delete_edges(el, vid)

Arguments

Value

Returns an updated edgelist object, with any edges including the specified vertices removed.

Description

Given a current two-column matrix of edges and a vector of IDs to delete from the matrix, this function first removes any rows of the edgelist in which the IDs are present and then permutes downward the index of IDs on the edgelist that were numerically larger than the IDs deleted.

Usage

delete_vertices(el, vid)

Arguments

Details

This function is used in EpiModel modules to remove vertices (nodes) from the edgelist object to account for exits from the population (e.g., deaths and out-migration).

Value

Returns an updated edgelist object, el, with the edges of deleted vertices removed from the edgelist and the ID numbers of the remaining edges permuted downward.

Examples

## Not run: 
library("EpiModel")
set.seed(12345)
nw <- network_initialize(100)
formation <- ~edges
target.stats <- 50
coef.diss <- dissolution_coefs(dissolution = ~offset(edges), duration = 20)
x <- netest(nw, formation, target.stats, coef.diss, verbose = FALSE)

param <- param.net(inf.prob = 0.3)
init <- init.net(i.num = 10)
control <- control.net(type = "SI", nsteps = 100, nsims = 5,
                       tergmLite = TRUE)

# Set seed for reproducibility
set.seed(123456)

# networkLite representation structure after initialization
dat <- crosscheck.net(x, param, init, control)
dat <- initialize.net(x, param, init, control)

# Current edges
head(dat$el[[1]], 20)

# Remove nodes 1 and 2
nodes.to.delete <- 1:2
dat$el[[1]] <- delete_vertices(dat$el[[1]], nodes.to.delete)

# Newly permuted edges
head(dat$el[[1]], 20)

## End(Not run)

Description

Depart Nodes from the netsim_dat Object

Usage

depart_nodes(dat, departures)

Arguments

Details

If tergmLite is FALSE, the vertex ids departures are deactivated (from the current timestep onward) in each networkDynamic stored in dat$nw. If tergmLite is TRUE, the vertex ids departures are deleted from dat$el, dat$attr, and dat$net_attr.

Value

the updated netsim_dat object with the nodes in departures departed

Description

Calculates dissolution coefficients, given a dissolution model and average edge duration, to pass as offsets to an ERGM/TERGM model fit in netest.

Usage

dissolution_coefs(dissolution, duration, d.rate = 0)

Arguments

Details

This function performs two calculations for dissolution coefficients used in a network model estimated with netest:

1. Transformation: the mean durations of edges in a network are mathematically transformed to logit coefficients.

2. Adjustment: in a dynamic network simulation in an open population (in which there are departures), it is further necessary to adjust these coefficients; this upward adjustment accounts for departure as a competing risk to edge dissolution.

The current dissolution models supported by this function and in network model estimation in netest are as follows:

• ~offset(edges): a homogeneous dissolution model in which the edge duration is the same for all partnerships. This requires specifying one duration value.

• ~offset(edges) + offset(nodematch("<attr>")): a heterogeneous model in which the edge duration varies by whether the nodes in the dyad have similar values of a specified attribute. The duration vector should now contain two values: the first is the mean edge duration of non-matched dyads, and the second is the duration of the matched dyads.

• ~offset(edges) + offset(nodemix("<attr>")): a heterogeneous model that extends the nodematch model to include non-binary attributes for homophily. The duration vector should first contain the base value, then the values for every other possible combination in the term.

Value

A list of class disscoef with the following elements:

• dissolution: right-hand sided STERGM dissolution formula passed in the function call.

• duration: mean edge durations passed into the function.

• coef.crude: mean durations transformed into logit coefficients.

• coef.adj: crude coefficients adjusted for the risk of departure on edge persistence, if the d.rate argument is supplied.

• coef.form.corr: corrections to be subtracted from formation coefficients.

• d.rate: the departure rate.

• diss.model.type: the form of the dissolution model; options include edgesonly, nodematch, and nodemix.

Examples

## Homogeneous dissolution model with no departures
dissolution_coefs(dissolution = ~offset(edges), duration = 25)

## Homogeneous dissolution model with departures
dissolution_coefs(dissolution = ~offset(edges), duration = 25,
                  d.rate = 0.001)

## Heterogeneous dissolution model in which same-race edges have
## shorter duration compared to mixed-race edges, with no departures
dissolution_coefs(dissolution = ~offset(edges) + offset(nodematch("race")),
                  duration = c(20, 10))

## Heterogeneous dissolution model in which same-race edges have
## shorter duration compared to mixed-race edges, with departures
dissolution_coefs(dissolution = ~offset(edges) + offset(nodematch("race")),
                  duration = c(20, 10), d.rate = 0.001)

## Not run: 
## Extended example for differential homophily by age group
# Set up the network with nodes categorized into 5 age groups
nw <- network_initialize(n = 1000)
age.grp <- sample(1:5, 1000, TRUE)
nw <- set_vertex_attribute(nw, "age.grp", age.grp)

# durations = non-matched, age.grp1 & age.grp1, age.grp2 & age.grp2, ...
# TERGM will include differential homophily by age group with nodematch term
# Target stats for the formation model are overall edges, and then the number
# matched within age.grp 1, age.grp 2, ..., age.grp 5
form <- ~edges + nodematch("age.grp", diff = TRUE)
target.stats <- c(450, 100, 125, 40, 80, 100)

# Target stats for the dissolution model are duration of non-matched edges,
# then duration of edges matched within age.grp 1, age.grp 2, ..., age.grp 5
durs <- c(60, 30, 80, 100, 125, 160)
diss <- dissolution_coefs(~offset(edges) +
                            offset(nodematch("age.grp", diff = TRUE)),
                          duration = durs)

# Fit the TERGM
fit <- netest(nw, form, target.stats, diss)

# Full diagnostics to evaluate model fit
dx <- netdx(fit, nsims = 10, ncores = 4, nsteps = 300)
print(dx)

# Simulate one long time series to examine timed edgelist
dx <- netdx(fit, nsims = 1, nsteps = 5000, keep.tedgelist = TRUE)

# Extract timed-edgelist
te <- as.data.frame(dx)
head(te)

# Limit to non-censored edges
te <- te[which(te$onset.censored == FALSE & te$terminus.censored == FALSE),
         c("head", "tail", "duration")]
head(te)

# Look up the age group of head and tail nodes
te$ag.head <- age.grp[te$head]
te$ag.tail <- age.grp[te$tail]
head(te)

# Recover average edge durations for age-group pairing
mean(te$duration[te$ag.head != te$ag.tail])
mean(te$duration[te$ag.head == 1 & te$ag.tail == 1])
mean(te$duration[te$ag.head == 2 & te$ag.tail == 2])
mean(te$duration[te$ag.head == 3 & te$ag.tail == 3])
mean(te$duration[te$ag.head == 4 & te$ag.tail == 4])
mean(te$duration[te$ag.head == 5 & te$ag.tail == 5])
durs

## End(Not run)

Description

Outputs a table of the number and percent of edges that are left-censored, right-censored, both-censored, or uncensored for a networkDynamic object.

Usage

edgelist_censor(el)

Arguments

Details

Given a STERGM simulation over a specified number of time steps, the edges within that simulation may be left-censored (started before the first step), right-censored (continued after the last step), right and left-censored, or uncensored. The amount of censoring will increase when the average edge duration approaches the length of the simulation.

Value

A 4 x 2 table containing the number and percent of edges in el that are left-censored, right-censored, both-censored, or uncensored.

Examples

# Initialize and parameterize network model
nw <- network_initialize(n = 100)
formation <- ~edges
target.stats <- 50
coef.diss <- dissolution_coefs(dissolution = ~offset(edges), duration = 20)

# Model estimation
est <- netest(nw, formation, target.stats, coef.diss, verbose = FALSE)

# Simulate the network and extract a timed edgelist
dx <- netdx(est, nsims = 1, nsteps = 100, keep.tedgelist = TRUE,
      verbose = FALSE)
el <- as.data.frame(dx)

# Calculate censoring
edgelist_censor(el)

Description

Runs a web browser-based GUI of deterministic compartmental models, stochastic individual contact models, and basic network models.

Usage

epiweb(class, ...)

Arguments

Details

epiweb runs a web-based GUI of one-group deterministic compartmental models, stochastic individual contact models, and stochastic network models with user input on model type, state sizes, and parameters. Model output may be plotted, summarized, and saved as raw data using the core EpiModel functionality for these model classes. These applications are built using the shiny package framework.

References

RStudio. shiny: Web Application Framework for R. R package version 1.0.5. 2015. https://shiny.posit.co/.

See Also

dcm, icm, netsim

Examples

## Not run: 
## Deterministic compartmental models
epiweb(class = "dcm")

## Stochastic individual contact models
epiweb(class = "icm")

## Stochastic network models
epiweb(class = "net")

## End(Not run)

Description

This function uses the generative functions in the random.params list to create values for the parameters.

Usage

generate_random_params(param, verbose = FALSE)

Arguments

Value

A fully instantiated param list.

random.params

The random.params argument to the param.net function must be a named list of functions that each return a value that can be used as the argument with the same name. In the example below, param_random is a function factory provided by EpiModel for act.rate and for tx.halt.part.prob we provide bespoke functions. A function factory is a function that returns a new function (see https://adv-r.hadley.nz/function-factories.html).

Generator Functions

The functions used inside random_params must be 0 argument functions returning a valid value for the parameter with the same name.

param_random_set

The random_params list can optionally contain a param_random_set element. It must be a data.frame of possible values to be used as parameters.

The column names must correspond either to: the name of one parameter, if this parameter is of size 1; or the name of one parameter with "_1", "2", etc. appended, with the number representing the position of the value, if this parameter is of size > 1. This means that the parameter names cannot contain any underscores "" if you intend to use param_random_set.

The point of the param.random.set data.frame is to allow the random parameters to be correlated. To achieve this, a whole row of the data.frame is selected for each simulation.

Examples

## Not run: 

## Example with only the generator function

# Define random parameter list
my_randoms <- list(
  act.rate = param_random(c(0.25, 0.5, 0.75)),
  tx.prob = function() rbeta(1, 1, 2),
  stratified.test.rate = function() c(
    rnorm(1, 0.05, 0.01),
    rnorm(1, 0.15, 0.03),
    rnorm(1, 0.25, 0.05)
  )
)

# Parameter model with fixed and random parameters
param <- param.net(inf.prob = 0.3, random.params = my_randoms)

# Below, `tx.prob` is set first to 0.3 then assigned a random value using
# the function from `my_randoms`. A warning notifying of this overwrite is
# therefore produced.
param <- param.net(tx.prob = 0.3, random.params = my_randoms)


# Parameters are drawn automatically in netsim by calling the function
# within netsim_loop. Demonstrating draws here but this is not used by
# end user.
paramDraw <- generate_random_params(param, verbose = TRUE)
paramDraw


## Addition of the `param.random.set` `data.frame`

# This function will generate sets of correlated parameters
 generate_correlated_params <- function() {
   param.unique <- runif(1)
   param.set.1 <- param.unique + runif(2)
   param.set.2 <- param.unique * rnorm(3)

   return(list(param.unique, param.set.1, param.set.2))
 }

 # Data.frame set of random parameters :
 correlated_params <- t(replicate(10, unlist(generate_correlated_params())))
 correlated_params <- as.data.frame(correlated_params)
 colnames(correlated_params) <- c(
   "param.unique",
   "param.set.1_1", "param.set.1_2",
   "param.set.2_1", "param.set.2_2", "param.set.2_3"
 )

# Define random parameter list with the `param.random.set` element
my_randoms <- list(
  act.rate = param_random(c(0.25, 0.5, 0.75)),
  param.random.set = correlated_params
)

# Parameter model with fixed and random parameters
param <- param.net(inf.prob = 0.3, random.params = my_randoms)

# Parameters are drawn automatically in netsim by calling the function
# within netsim_loop. Demonstrating draws here but this is not used by
# end user.
paramDraw <- generate_random_params(param, verbose = TRUE)
paramDraw


## End(Not run)

Description

Plots quantile bands given a data.frame with stochastic model results from icm or netsim.

Usage

geom_bands(mapping, lower = 0.25, upper = 0.75, alpha = 0.25, ...)

Arguments

Details

This is a wrapper around ggplot::stat_summary with a ribbon geom as aesthetic output.

Examples

param <- param.icm(inf.prob = 0.2, act.rate = 0.25)
init <- init.icm(s.num = 500, i.num = 1)
control <- control.icm(type = "SI", nsteps = 250, nsims = 5)
mod1 <- icm(param, init, control)
df <- as.data.frame(mod1)
df.mean <- as.data.frame(mod1, out = "mean")

library(ggplot2)
ggplot() +
   geom_line(data = df, mapping = aes(time, i.num, group = sim),
   alpha = 0.25, lwd = 0.25, color = "firebrick") +
   geom_bands(data = df, mapping = aes(time, i.num),
              lower = 0.1, upper = 0.9, fill = "firebrick") +
   geom_line(data = df.mean, mapping = aes(time, i.num)) +
   theme_minimal()

Description

Returns an adjacency list from an edge list

Usage

get_adj_list(el, n_nodes)

Arguments

Details

The adjacency list is a list of length n_nodes. The entry for each node is a integer vector containing the index of all the nodes connected to it. This layout makes it directly subsetable in O(1) at the expanse of memory usage. To get all connections to the nodes 10 and 15 : ⁠unlist(adj_list[c(10, 15)]⁠

Value

An adjacency list for the network

Description

Extract the Attributes History from Network Simulations

Usage

get_attr_history(sims)

Arguments

Value

A list of data.frames, one for each "measure" recorded in the simulation by the record_attr_history function.

Examples

## Not run: 

# With `sims` the result of a `netsim` call
get_attr_history(sims)


## End(Not run)

Description

Returns all the node connected directly or indirectly to a set of nodes

Usage

get_connected_nodes(adj_list, nodes)

Arguments

Value

A vector of nodes indexes that are connected together with the ones provided in the nodes argument. The nodes themselves are not listed in this output

Description

Return the Cumulative Degree of a Set of Index Nodes

Usage

get_cumulative_degree(
  dat,
  index_posit_ids,
  networks = NULL,
  truncate = Inf,
  only.active.nodes = FALSE
)

Arguments

Value

A data.frame with 2 columns:

• index_pid: the positional ID (see get_posit_ids) of the indexes.

• degree: the cumulative degree of the index.

Cumulative Degree

The cumulative degree of a node is the number of edges connected to this node at during the time window. The time window is by default all the steps stored in the cumulative_edgelist or set by the truncate parameter.

Description

Get a Cumulative Edgelist From a Specified Network

Usage

get_cumulative_edgelist(dat, network)

Arguments

Value

A cumulative edgelist in data.frame form with 4 columns:

• head: the unique ID (see get_unique_ids) of the head node on the edge.

• tail: the unique ID (see get_unique_ids) of the tail node on the edge.

• start: the time step in which the edge started.

• stop: the time step in which the edge stopped; if ongoing, then NA is returned.

Description

Get the Cumulative Edgelists of a Model

Usage

get_cumulative_edgelists_df(dat, networks = NULL)

Arguments

Value

A data.frame with 5 columns:

• index: the unique ID (see get_unique_ids) of the indexes.

• partner: the unique ID (see get_unique_ids) of the partners/contacts.

• start: the time step in which the edge started.

• stop: the time step in which the edge stopped; if ongoing, then NA is returned.

• network: the numerical index for the network on which the partnership/contact is located.

Description

Return the Current Timestep

Usage

get_current_timestep(dat)

Arguments

Value

The current timestep.

Description

A fast method for querying the current degree of all individuals within a network.

Usage

get_degree(x)

Arguments

Details

Individual-level data on the current degree of nodes within a network is often useful for summary statistics. Given a network class object, net, one way to look up the current degree is to get a summary of the ERGM term, sociality, as in: summary(net ~ sociality(nodes = NULL)). But that is computationally inefficient for a number of reasons. This function provides a fast method for generating the vector of degrees using a query of the edgelist. It is even faster if the parameter x is already transformed into an edgelist.

Value

A vector of length equal to the total network size, containing the current degree of each node in the network.

Examples

nw <- network_initialize(n = 500)

set.seed(1)
fit <- ergm(nw ~ edges, target.stats = 250)
sim <- simulate(fit)

# Slow ERGM-based method
ergm.method <- unname(summary(sim ~ sociality(nodes = NULL)))
ergm.method

# Fast tabulate method with network object
deg.net <- get_degree(sim)
deg.net

# Even faster if network already transformed into an edgelist
el <- as.edgelist(sim)
deg.el <- get_degree(el)
deg.el

identical(as.integer(ergm.method), deg.net, deg.el)

Description

This function outputs an edgelist from the specified network, selecting the method depending on the stored network type.

Usage

get_edgelist(dat, network)

Arguments

Value

An edgelist in matrix form with two columns. Each column contains the posit_ids (see get_posit_ids) of the nodes in each edge.

Description

Get the Edgelist(s) from the Specified Network(s)

Usage

get_edgelists_df(dat, networks = NULL)

Arguments

Value

A data.frame with the following columns:

• head: Positional ID of the head node.

• tail: Positional ID of the tail node.

• network: The numerical index of the network on which the edge is located.

Description

Given a formation formula for a network model, outputs a character vector of vertex attributes to be used in netsim simulations.

Usage

get_formula_term_attr(form, nw)

Arguments

Value

A character vector of vertex attributes.

Description

Extracts the network object from either a network epidemic model object generated with netsim, a network diagnostic simulation generated with netdx, or a netsim_dat object used internally in netsim. For netdx or netsim with tergmLite == FALSE, the extracted network object is a networkDynamic, which can be collapsed down to a static network object with the collapse and at arguments. For netsim with tergmLite == TRUE, the extracted network object is the final networkLite, the collapse argument should be FALSE, and the at argument should be missing. For netsim_dat, the collapse and at arguments are not supported, and the network object is either the current networkLite (if tergmLite == TRUE) or the current networkDynamic (if tergmLite == FALSE).

Usage

get_network(x, ...)

## S3 method for class 'netdx'
get_network(x, sim = 1, collapse = FALSE, at, ...)

## S3 method for class 'netsim'
get_network(x, sim = 1, network = 1, collapse = FALSE, at, ...)

## S3 method for class 'netsim_dat'
get_network(x, network = 1L, ...)

Arguments

Details

This function requires that the network object is saved during the network simulation while running either netsim or netdx. For the former, that is specified by setting the save.network parameter in control.net to TRUE. For the latter, that is specified with the keep.tnetwork parameter directly in netdx.

Value

For netdx or netsim with tergmLite == FALSE, a networkDynamic object (if collapse = FALSE) or a static network object (if collapse = TRUE). For netsim with tergmLite == TRUE or netsim_dat with tergmLite == TRUE, a networkLite object. For netsim_dat with tergmLite == FALSE, a networkDynamic object.

Examples

# Set up network and TERGM formula
nw <- network_initialize(n = 100)
nw <- set_vertex_attribute(nw, "group", rep(1:2, each = 50))
formation <- ~edges
target.stats <- 50
coef.diss <- dissolution_coefs(dissolution = ~offset(edges), duration = 20)

# Estimate the model
est <- netest(nw, formation, target.stats, coef.diss)

# Run diagnostics, saving the networkDynamic objects
dx <- netdx(est, nsteps = 10, nsims = 3, keep.tnetwork = TRUE,
            verbose = FALSE)

# Extract the network for simulation 2 from dx object
get_network(dx, sim = 2)

# Extract and collapse the network from simulation 1 at time step 5
get_network(dx, collapse = TRUE, at = 5)

# Parameterize the epidemic model, and simulate it
param <- param.net(inf.prob = 0.3, inf.prob.g2 = 0.15)
init <- init.net(i.num = 10, i.num.g2 = 10)
control <- control.net(type = "SI", nsteps = 10, nsims = 3, verbose = FALSE)
mod <- netsim(est, param, init, control)

# Extract the network for simulation 2 from mod object
get_network(mod, sim = 2)

## Extract and collapse the network from simulation 1 at time step 5
get_network(mod, collapse = TRUE, at = 5)

Description

Gets all network attributes except "mnext" from its network argument.

Usage

get_network_attributes(x)

Arguments

Details

This function is used in EpiModel workflows to copy relevant network attributes from the network object to the netsim_dat object when initializing netsim runs.

Value

Returns the named list of network attributes.

Examples

nw <- network_initialize(100)
get_network_attributes(nw)

Description

Given a simulated network, outputs a character vector of vertex attributes to be used in netsim simulations.

Usage

get_network_term_attr(nw)

Arguments

Value

A character vector of vertex attributes.

Description

Extracts network statistics from a network epidemic model simulated with netsim or a network diagnostics object simulated with netdx. Statistics can be returned either as a single data frame or as a list of matrices (one matrix for each simulation).

Usage

get_nwstats(x, sim, network = 1, mode = c("data.frame", "list"))

Arguments

Value

A data frame or list of matrices containing the network statistics.

Examples

# Two-group Bernoulli random graph TERGM
nw <- network_initialize(n = 100)
nw <- set_vertex_attribute(nw, "group", rep(1:2, each = 50))
formation <- ~edges
target.stats <- 50
coef.diss <- dissolution_coefs(dissolution = ~offset(edges), duration = 20)
est <- netest(nw, formation, target.stats, coef.diss, verbose = FALSE)

dx <- netdx(est, nsim = 3, nsteps = 10, verbose = FALSE,
            nwstats.formula = ~edges + isolates)
get_nwstats(dx)
get_nwstats(dx, sim = 1)

# SI epidemic model
param <- param.net(inf.prob = 0.3, inf.prob.g2 = 0.15)
init <- init.net(i.num = 10, i.num.g2 = 10)
control <- control.net(type = "SI", nsteps = 10, nsims = 3,
                       nwstats.formula = ~edges + meandeg + degree(0:5),
                       verbose = FALSE)
mod <- netsim(est, param, init, control)

# Extract the network statistics from all or sets of simulations
get_nwstats(mod)
get_nwstats(mod, sim = 2)
get_nwstats(mod, sim = c(1, 3))

# On the fly summary stats
summary(get_nwstats(mod))
colMeans(get_nwstats(mod))

Description

Extract the Parameter Set from Network Simulations

Usage

get_param_set(sims)

Arguments

Value

A data.frame with one row per simulation and one column per parameter or parameter element where the parameters are of size > 1.

Output Format

The outputted data.frame has one row per simulation and the columns correspond to the parameters used in this simulation.

The column name will match the parameter name if it is a size 1 parameter or if the parameter is of size > 1, there will be N columns (with N being the size of the parameter) named parameter.name_1, parameter.name_2, ..., parameter.name_N.

Examples

# Setup network
nw <- network_initialize(n = 50)

est <- netest(
  nw, formation = ~edges,
  target.stats = c(25),
  coef.diss = dissolution_coefs(~offset(edges), 10, 0),
  verbose = FALSE
)

init <- init.net(i.num = 10)

n <- 5

related.param <- data.frame(
  dummy.param = rbeta(n, 1, 2)
)

 my.randoms <- list(
   act.rate = param_random(c(0.25, 0.5, 0.75)),
   dummy.param = function() rbeta(1, 1, 2),
   dummy.strat.param = function() c(
     rnorm(1, 0, 10),
     rnorm(1, 10, 1)
   )
 )

param <- param.net(
  inf.prob = 0.3,
  dummy = c(0, 1, 2),
  random.params = my.randoms
)

control <- control.net(type = "SI", nsims = 3, nsteps = 5, verbose = FALSE)
mod <- netsim(est, param, init, control)

get_param_set(mod)

Description

From a full cumulative edgelist that contains the history of contacts (both persistent and one-time), this function returns a data frame containing details of the index (head) and partner (tail) nodes, along with start and stop time steps for the partnership and the network location.

Usage

get_partners(
  dat,
  index_posit_ids,
  networks = NULL,
  truncate = Inf,
  only.active.nodes = FALSE
)

Arguments

Details

Note that get_partners takes as input the positional IDs of the indexes of interest but returns the unique IDs. That is by design, because while get_partners would be expected to be called for active nodes, some partners (contacts) of nodes may be inactive in the network history. Therefore, both index and partner IDs are returned as unique IDs for consistency. To convert between a positional to a unique ID, you may use get_posit_ids; to convert between a unique ID to a positional ID, you may use get_unique_ids.

Value

A data.frame with 5 columns:

• index: the unique IDs of the indexes.

• partner: the unique IDs of the partners/contacts.

• start: the time step at which the edge started.

• stop: the time step in which the edge stopped; if ongoing, then NA is returned.

• network: the numerical index for the network on which the partnership/contact is located.

Description

Subsets the entire netsim object to a subset of simulations, essentially functioning like a reverse of merge.

Usage

get_sims(x, sims, var)

Arguments

Value

An updated object of class netsim containing only the simulations specified in sims and the variables specified in var.

Examples

# Network model estimation
nw <- network_initialize(n = 100)
formation <- ~edges
target.stats <- 50
coef.diss <- dissolution_coefs(dissolution = ~offset(edges), duration = 20)
est1 <- netest(nw, formation, target.stats, coef.diss, verbose = FALSE)

# Epidemic model
param <- param.net(inf.prob = 0.3)
init <- init.net(i.num = 10)
control <- control.net(type = "SI", nsteps = 10, nsims = 3, verbose.int = 0)
mod1 <- netsim(est1, param, init, control)

# Get sim 2
s.g2 <- get_sims(mod1, sims = 2)

# Get sims 2 and 3 and keep only a subset of variables
s.g2.small <- get_sims(mod1, sims = 2:3, var = c("i.num", "si.flow"))

# Extract the mean simulation for the variable i.num
sim.mean <- get_sims(mod1, sims = "mean", var = "i.num")

Description

Return an adjacency list of subnets

Usage

get_subnet_adj_list(adj_list)

Arguments

Details

A graph with 4 components: 1, 2, 3, 4, and 5 and 6, 7, 8 would yield a list like so: 1: 2, 3, 4 2: 1 3: 1 4: 1 5: numeric(0) 6: 7, 8 7: 6, 8: 6

This format speeds up the construction of reachable sets on dense networks

Value

An adjacency list where only the first node of a subnet contains the subnet and all other contain only the first node

Description

Gets a vertex attribute from an object of class network. This functions simplifies the related function in the network package.

Usage

get_vertex_attribute(x, attrname)

Arguments

Details

This function is used in EpiModel workflows to query vertex attributes on an initialized empty network object (see network_initialize).

Value

Returns an object of class network.

Examples

nw <- network_initialize(100)
nw <- set_vertex_attribute(nw, "age", runif(100, 15, 65))
get_vertex_attribute(nw, "age")

Description

Simulates stochastic individual contact epidemic models for infectious disease.

Usage

icm(param, init, control)

Arguments

Details

Individual contact models are intended to be the stochastic microsimulation analogs to deterministic compartmental models. ICMs simulate disease spread on individual agents in discrete time as a function of processes with stochastic variation. The stochasticity is inherent in all transition processes: infection, recovery, and demographics.

The icm function performs modeling of both the base model types and original models. Base model types include one-group and two-group models with disease types for Susceptible-Infected (SI), Susceptible-Infected-Recovered (SIR), and Susceptible-Infected-Susceptible (SIS). Original models may be built by writing new process modules that either take the place of existing modules (for example, disease recovery), or supplement the set of existing processes with a new one contained in an original module.

Value

A list of class icm with the following elements:

• param: the epidemic parameters passed into the model through param, with additional parameters added as necessary.

• control: the control settings passed into the model through control, with additional controls added as necessary.

• epi: a list of data frames, one for each epidemiological output from the model. Outputs for base models always include the size of each compartment, as well as flows in, out of, and between compartments.

See Also

Extract the model results with as.data.frame.icm. Summarize the time-specific model results with summary.icm. Plot the model results with plot.icm. Plot a compartment flow diagram with comp_plot.

Examples

## Not run: 
## Example 1: SI Model
param <- param.icm(inf.prob = 0.2, act.rate = 0.25)
init <- init.icm(s.num = 500, i.num = 1)
control <- control.icm(type = "SI", nsteps = 500, nsims = 10)
mod1 <- icm(param, init, control)
mod1
plot(mod1)

## Example 2: SIR Model
param <- param.icm(inf.prob = 0.2, act.rate = 0.25, rec.rate = 1/50)
init <- init.icm(s.num = 500, i.num = 1, r.num = 0)
control <- control.icm(type = "SIR", nsteps = 500, nsims = 10)
mod2 <- icm(param, init, control)
mod2
plot(mod2)

## Example 3: SIS Model
param <- param.icm(inf.prob = 0.2, act.rate = 0.25, rec.rate = 1/50)
init <- init.icm(s.num = 500, i.num = 1)
control <- control.icm(type = "SIS", nsteps = 500, nsims = 10)
mod3 <- icm(param, init, control)
mod3
plot(mod3)

## Example 4: SI Model with Vital Dynamics (Two-Group)
param <- param.icm(inf.prob = 0.4,  inf.prob.g2 = 0.1,
                   act.rate = 0.25, balance = "g1",
                   a.rate = 1/100, a.rate.g2 = NA,
                   ds.rate = 1/100, ds.rate.g2 = 1/100,
                   di.rate = 1/50, di.rate.g2 = 1/50)
init <- init.icm(s.num = 500, i.num = 1,
                 s.num.g2 = 500, i.num.g2 = 0)
control <- control.icm(type = "SI", nsteps = 500, nsims = 10)
mod4 <- icm(param, init, control)
mod4
plot(mod4)

## End(Not run)

Description

This function adds 1 to the timestep counter stored in the netsim_dat main list object.

Usage

increment_timestep(dat)

Arguments

Value

The updated netsim_dat main list object.

Mutability

This DOES NOT modify the netsim_dat object in place. The result must be assigned back to dat in order to be registered: dat <- increment_timestep(dat).

Description

Sets the initial conditions for deterministic compartmental models simulated with dcm.

Usage

init.dcm(s.num, i.num, r.num, s.num.g2, i.num.g2, r.num.g2, ...)

Arguments

Details

The initial conditions for a model solved with dcm should be input into the init.dcm function. This function handles initial conditions for both base model types and original models.

Original models may use the parameter names listed as arguments here, a new set of names, or a combination of both. With new models, initial conditions must be input in the same order that the solved derivatives from the model are output.

Value

An EpiModel object of class init.dcm.

See Also

Use param.dcm to specify model parameters and control.dcm to specify the control settings. Run the parameterized model with dcm.

Description

Sets the initial conditions for stochastic individual contact models simulated with icm.

Usage

init.icm(s.num, i.num, r.num, s.num.g2, i.num.g2, r.num.g2, ...)

Arguments

Details

The initial conditions for a model solved with icm should be input into the init.icm function. This function handles initial conditions for both base models and original models using new modules.

Value

An EpiModel object of class init.icm.

See Also

Use param.icm to specify model parameters and control.icm to specify the control settings. Run the parameterized model with icm.

Description

Sets the initial conditions for stochastic network models simulated with netsim.

Usage

init.net(i.num, r.num, i.num.g2, r.num.g2, status.vector, infTime.vector, ...)

Arguments

Details

The initial conditions for a model solved with netsim should be input into the init.net function. This function handles initial conditions for both base models and new modules. For an overview of specifying initial conditions across a variety of base network models, consult the Network Modeling for Epidemics tutorials.

Value

An EpiModel object of class init.net.

See Also

Use param.net to specify model parameters and control.net to specify the control settings. Run the parameterized model with netsim.

Examples

# Example of using status.vector and infTime.vector together
n <- 100
status <- sample(c("s", "i"), size = n, replace = TRUE, prob = c(0.8, 0.2))
infTime <- rep(NA, n)
infTime[which(status == "i")] <- -rgeom(sum(status == "i"), prob = 0.01) + 2

init.net(status.vector = status, infTime.vector = infTime)

Description

This function defines and initializes the absdiffby ERGM term that allows for representing homophily with respect to a non-binary attribute (e.g., age) differentially by a binary attribute (e.g., sex).

Usage

InitErgmTerm.absdiffby(nw, arglist, ...)

Arguments

Details

This ERGM user term was written to allow for age-based homophily in partnership formation that is asymmetric by sex. The absdiff component targets age-based homophily while the by component allows that to be structured by a binary attribute such as "male", in order to enforce an offset in the average difference. This allows, for example, a average age difference in partnerships, but with males (on average) older than females.

Description

This function defines and initializes the absdiffnodemix ERGM term that allows for targeting homophily based on a non-binary attribute (e.g., age) by combinations of a binary attribute (e.g., race).

Usage

InitErgmTerm.absdiffnodemix(nw, arglist, ...)

Arguments

Details

This ERGM user term was written to allow for age-based homophily in partnership formation that is heterogeneous by race. The absdiff component targets the distribution of age mixing on that continuous variable, and the nodemix component differentiates this for black-black, black-white, and white-white couples.

Description

This function defines and initializes the fuzzynodematch ERGM term that allows for generalized homophily.

Usage

InitErgmTerm.fuzzynodematch(nw, arglist, ...)

Arguments

Details

This ERGM user term was written to allow for generalized homophily.The attr term argument should specify a character vertex attribute encoding the "venues" associated to each node. The split argument should specify a string that separates different "venues" in the attribute value for each node, as handled by strsplit with fixed = TRUE. For example, if split is "|" (the default), and the attribute value for a given node is "a12|b476", then the associated venues for this node are "a12" and "b476". The empty string "" is interpreted as "no venues".

If the binary term argument is FALSE (the default), the change statistic for an on-toggle is the number of unique venues associated to both nodes (informally speaking, this could be described as the number of venues on which the two nodes "match"); if binary is TRUE, the change statistic for an on-toggle is 1 if any venue is associated to both nodes, and 0 otherwise.

Description

Are These Nodes Active (Positional IDs)

Usage

is_active_posit_ids(dat, posit_ids)

Arguments

Value

A logical vector with TRUE if the node is still active and FALSE otherwise.

Description

Are These Nodes Active (Unique IDs)

Usage

is_active_unique_ids(dat, unique_ids)

Arguments

Value

A logical vector with TRUE if the node is still active and FALSE otherwise.

Description

Extracts the matrix of transmission data for each transmission event that occurred within a network epidemic model.

Usage

is.transmat(x)

get_transmat(x, sim = 1, deduplicate = TRUE)

Arguments

Value

A data frame with the following standard columns:

• at: the time step at which the transmission occurred.

• sus: the ID number of the susceptible (newly infected) node.

• inf: the ID number of the infecting node.

• infDur: the duration of the infecting node's disease at the time of the transmission.

• transProb: the probability of transmission per act.

• actRate: the rate of acts per unit time.

• finalProb: the final transmission probability for the transmission event.

Examples

## Simulate SI epidemic on two-group Bernoulli random graph
nw <- network_initialize(n = 100)
nw <- set_vertex_attribute(nw, "group", rep(1:2, each = 50))
formation <- ~edges
target.stats <- 50
coef.diss <- dissolution_coefs(dissolution = ~offset(edges), duration = 20)
est <- netest(nw, formation, target.stats, coef.diss, verbose = FALSE)
param <- param.net(inf.prob = 0.3, inf.prob.g2 = 0.15)
init <- init.net(i.num = 10, i.num.g2 = 10)
control <- control.net(type = "SI", nsteps = 10, nsims = 3, verbose = FALSE)
mod <- netsim(est, param, init, control)

## Extract the transmission matrix from simulation 2
get_transmat(mod, sim = 2)

Description

Merges epidemiological data from two independent simulations of stochastic individual contact models from icm.

Usage

## S3 method for class 'icm'
merge(x, y, ...)

Arguments

Details

This merge function combines the results of two independent simulations of icm class models, simulated under separate function calls. The model parameterization between the two calls must be exactly the same, except for the number of simulations in each call. This allows for manual parallelization of model simulations.

This merge function does not work the same as the default merge, which allows for a combined object where the structure differs between the input elements. Instead, the function checks that objects are identical in model parameterization in every respect (except number of simulations) and binds the results.

Value

An EpiModel object of class icm containing the data from both x and y.

Examples

param <- param.icm(inf.prob = 0.2, act.rate = 0.8)
init <- init.icm(s.num = 1000, i.num = 100)
control <- control.icm(type = "SI", nsteps = 10,
                       nsims = 3, verbose = FALSE)
x <- icm(param, init, control)

control <- control.icm(type = "SI", nsteps = 10,
                       nsims = 1, verbose = FALSE)
y <- icm(param, init, control)

z <- merge(x, y)

# Examine separate and merged data
as.data.frame(x)
as.data.frame(y)
as.data.frame(z)

Description

Merges epidemiological data from two independent simulations of stochastic network models from netsim.

Usage

## S3 method for class 'netsim'
merge(
  x,
  y,
  keep.transmat = TRUE,
  keep.network = TRUE,
  keep.nwstats = TRUE,
  keep.other = TRUE,
  param.error = TRUE,
  keep.diss.stats = TRUE,
  ...
)

Arguments

Details

This merge function combines the results of two independent simulations of netsim class models, simulated under separate function calls. The model parameterization between the two calls must be exactly the same, except for the number of simulations in each call. This allows for manual parallelization of model simulations.

This merge function does not work the same as the default merge, which allows for a combined object where the structure differs between the input elements. Instead, the function checks that objects are identical in model parameterization in every respect (except number of simulations) and binds the results.

Value

An EpiModel object of class netsim containing the data from both x and y.

Examples

# Network model
nw <- network_initialize(n = 100)
coef.diss <- dissolution_coefs(dissolution = ~offset(edges), duration = 10)
est <- netest(nw, formation = ~edges, target.stats = 25,
              coef.diss = coef.diss, verbose = FALSE)

# Epidemic models
param <- param.net(inf.prob = 1)
init <- init.net(i.num = 1)
control <- control.net(type = "SI", nsteps = 20, nsims = 2,
                       save.nwstats = TRUE,
                       nwstats.formula = ~edges + degree(0),
                       verbose = FALSE)
x <- netsim(est, param, init, control)
y <- netsim(est, param, init, control)

# Merging
z <- merge(x, y)

# Examine separate and merged data
as.data.frame(x)
as.data.frame(y)
as.data.frame(z)

Description

Stochastic individual contact models of infectious disease simulate epidemics in which contacts between individuals are instantaneous events in discrete time. They are intended to be the stochastic microsimulation analogs to deterministic compartmental models.

The icm function handles both the simulation tasks. Within this function are a series of modules that initialize the simulation and then simulate new infections, recoveries, and vital dynamics at each time step. A module also handles the basic bookkeeping calculations for disease prevalence.

Writing original ICMs will require modifying the existing modules or adding new modules to the workflow in icm. The existing modules may be used as a template for replacement or new modules.

This help page presents a brief overview of the module functions in the order in which they are used within icm, in order to help guide users in writing their own module functions. These module functions are not shown on the help index since they are not called directly by the end-user. To understand these functions in more detail, review the separate help pages listed below.

Initialization Module

This function sets up agent attributes, like disease status, on the network at the starting time step of disease simulation, $t_1$. For multiple-simulation function calls, these are reset at the beginning of each simulation.

• initialize.icm: sets which agents are initially infected, through the initial conditions passed in init.icm.

Disease Status Modification Modules

The main disease simulation occurs at each time step given the current state of the population at that step. Infection of agents is simulated as a function of disease parameters and population composition. Recovery of agents is likewise simulated with respect to infected nodes. These functions also analyze the flows for summary measures such as disease incidence.

• infection.icm: randomly draws an edgelist given the parameters, subsets the list for discordant pairs, and simulates transmission on those discordant pairs through a series of draws from a binomial distribution.

• recovery.icm: simulates recovery from infection either to a lifelong immune state (for SIR models) or back to the susceptible state (for SIS models), as a function of the recovery rate specified in the rec.rate parameter. The recovery rate may vary for two-group models.

Demographic Modules

Vital dynamics such as arrival and departure processes are simulated at each time step to update entries into and exits from the population. These are used in open-population ICMs.

• departures.icm: randomly simulates departures or exits for agents given the departure rate specified in the disease-state and group-specific departure parameters in param.icm. This involves deactivating agents from the population, but their historical data is preserved in the simulation.

• arrivals.icm: randomly simulates new arrivals into the population given the current population size and the arrival rate parameters. This involves adding new agents into the population.

Bookkeeping Module

Simulations require bookkeeping at each time step to calculate the summary epidemiological statistics used in the model output analysis.

• prevalence.icm: calculates the number in each disease state (susceptible, infected, recovered) at each time step for those active agents in the population.

Description

Stochastic network models of infectious disease in EpiModel require statistical modeling of networks, simulation of those networks forward through time, and simulation of epidemic dynamics on top of those evolving networks. The netsim function handles both the network and epidemic simulation tasks. Within this function are a series of modules that initialize the simulation and then simulate new infections, recoveries, and demographics on the network. Modules also handle the resimulation of the network and some bookkeeping calculations for disease prevalence.

Writing original network models that expand upon our "base" model set will require modifying the existing modules or adding new modules to the workflow in netsim. The existing modules may be used as a template for replacement or new modules.

This help page provides an orientation to these module functions, in the order in which they are used within netsim, to help guide users in writing their own functions. These module functions are not shown on the help index since they are not called directly by the end-user. To understand these functions in more detail, review the separate help pages listed below.

Initialization Module

This function sets up nodal attributes, like disease status, on the network at the starting time step of disease simulation, $t_1$. For multiple-simulation function calls, these are reset at the beginning of each individual simulation.

• initialize.net: sets up the main netsim_dat data structure used in the simulation, initializes which nodes are infected (via the initial conditions passed in init.net), and simulates a first time step of the networks given the network model fit from netest.

Disease Status Modification Modules

The main disease simulation occurs at each time step given the current state of the network at that step. Infection of nodes is simulated as a function of attributes of the nodes and the edges. Recovery of nodes is likewise simulated as a function of nodal attributes of those infected nodes. These functions also calculate summary flow measures such as disease incidence.

• infection.net: simulates disease transmission given an edgelist of discordant partnerships by calculating the relevant transmission and act rates for each edge, and then updating the nodal attributes and summary statistics.

• recovery.net: simulates recovery from infection either to a lifelong immune state (for SIR models) or back to the susceptible state (for SIS models), as a function of the recovery rate parameters specified in param.net.

Demographic Modules

Demographics such as arrival and departure processes are simulated at each time step to update entries into and exits from the network. These are used in epidemic models with network feedback, in which the network is resimulated at each time step to account for the nodal changes affecting the edges.

• departures.net: randomly simulates departure for nodes given their disease status (susceptible, infected, recovered), and their group-specific departure rates specified in param.net. Departures involve deactivating nodes.

• arrivals.net: randomly simulates new arrivals into the network given the current population size and the arrival rate specified in the a.rate parameters. This involves adding new nodes into the network.

Network Resimulation Module

In dependent network models, the network object is resimulated at each time step to account for changes in the size of the network (changed through entries and exits), and the disease status of the nodes.

• resim_nets: resimulates the network object one time step forward given the set of formation and dissolution coefficients estimated in netest.

Bookkeeping Module

Network simulations require bookkeeping at each time step to calculate the summary epidemiological statistics used in the model output analysis.

• prevalence.net: calculates the number in each disease state (susceptible, infected, recovered) at each time step for those active nodes in the network. If the epi.by control is used, it calculates these statistics by a set of specified nodal attributes.

• verbose.net: summarizes the current state of the simulation and prints this to the console.

One- & Two-Group Modules

If epidemic type is supplied within control.net, EpiModel defaults each of the base epidemic and demographic modules described above (arrivals.FUN, departures.FUN, infection.FUN, recovery.FUN) to the correct .net function based on variables passed to param.net (e.g. num.g2, denoting population size of group two, would select the two-group variants of the aforementioned modules). Two-group modules are denoted by a .2g affix (e.g., recovery.2g.net)

Description

This utility function allows specification of certain netsim controls to vary by network. The netsim control arguments currently supporting multilayer specifications are nwstats.formula, set.control.ergm, set.control.tergm, and tergmLite.track.duration.

Usage

multilayer(...)

Arguments

Value

an object of class multilayer containing the specified control arguments

Description

Inspired by dplyr::mutate, mutate_epi adds new variables to the epidemiological and related variables within simulated model objects of any class in EpiModel.

Usage

mutate_epi(x, ...)

Arguments

Value

The updated EpiModel object of class dcm, icm, or netsim.

Examples

# DCM example
param <- param.dcm(inf.prob = 0.2, act.rate = 0.25)
init <- init.dcm(s.num = 500, i.num = 1)
control <- control.dcm(type = "SI", nsteps = 500)
mod1 <- dcm(param, init, control)
mod1 <- mutate_epi(mod1, prev = i.num/num)
plot(mod1, y = "prev")

# Network model example
nw <- network_initialize(n = 100)
nw <- set_vertex_attribute(nw, "group", rep(1:2, each = 50))
formation <- ~edges
target.stats <- 50
coef.diss <- dissolution_coefs(dissolution = ~offset(edges), duration = 20)
est1 <- netest(nw, formation, target.stats, coef.diss, verbose = FALSE)

param <- param.net(inf.prob = 0.3, inf.prob.g2 = 0.15)
init <- init.net(i.num = 1, i.num.g2 = 0)
control <- control.net(type = "SI", nsteps = 10, nsims = 3,
                       verbose = FALSE)
mod1 <- netsim(est1, param, init, control)
mod1

# Add the prevalences to the dataset
mod1 <- mutate_epi(mod1, i.prev = i.num / num,
                         i.prev.g2 = i.num.g2 / num.g2)
plot(mod1, y = c("i.prev", "i.prev.g2"), qnts = 0.5, legend = TRUE)

# Add incidence rate per 100 person years (assume time step = 1 week)
mod1 <- mutate_epi(mod1, ir100 = 5200*(si.flow + si.flow.g2) /
                                      (s.num + s.num.g2))
as.data.frame(mod1)
as.data.frame(mod1, out = "mean")

Description

These get_, set_, append_, and add_ functions allow a safe and efficient way to retrieve and mutate the main netsim_dat class object of network models (typical variable name dat).

Usage

get_attr_list(dat, item = NULL)

get_attr(dat, item, posit_ids = NULL, override.null.error = FALSE)

add_attr(dat, item)

set_attr(dat, item, value, posit_ids = NULL, override.length.check = FALSE)

append_attr(dat, item, value, n.new)

remove_node_attr(dat, posit_ids)

get_epi_list(dat, item = NULL)

get_epi(dat, item, at = NULL, override.null.error = FALSE)

add_epi(dat, item)

set_epi(dat, item, at, value)

get_param_list(dat, item = NULL)

get_param(dat, item, override.null.error = FALSE)

add_param(dat, item)

set_param(dat, item, value)

get_control_list(dat, item = NULL)

get_control(dat, item, override.null.error = FALSE)

get_network_control(dat, network, item, override.null.error = FALSE)

add_control(dat, item)

set_control(dat, item, value)

get_init_list(dat, item = NULL)

get_init(dat, item, override.null.error = FALSE)

add_init(dat, item)

set_init(dat, item, value)

append_core_attr(dat, at, n.new)

Arguments

Value

A vector or a list of vectors for get_ functions; the main list object for set_, append_, and add_ functions.

Core Attribute

The append_core_attr function initializes the attributes necessary for EpiModel to work (the four core attributes are: "active", "unique_id", "entrTime", and "exitTime"). These attributes are used in the initialization phase of the simulation, to create the nodes (see initialize.net); and also used when adding nodes during the simulation (see arrivals.net).

Mutability

The set_, append_, and add_ functions DO NOT modify the netsim_dat object in place. The result must be assigned back to dat in order to be registered: dat <- set_*(dat, item, value).

set_ and append_ vs add_