Tools for simulating mathematical models of infectious disease dynamics. Epidemic model classes include deterministic compartmental models, stochastic individual-contact models, and stochastic network models. Network models use the robust statistical methods of exponential-family random graph models (ERGMs) from the Statnet suite of software packages in R. Standard templates for epidemic modeling include SI, SIR, and SIS disease types. EpiModel features an API for extending these templates to address novel scientific research aims.
get_sims
and unit tests in plot.transmat
found
during CRAN submission for v1.7.1.get_args
and apportion_lr
, ported over from
EpiModelHIV.absdiffby
and absdiffnodemix
, ported over from
EpiModelHIV.as.data.frame.dcm
when dt
control setting < 1.keep.tnetwork
parameter to netdx
to allow for retaining the full
networkDynamic
object during dynamic network simulations. Relatedly, add
support for get_network
to extract those networks from netdx
objects.as.data.frame
function for processing model
output for all three model classes (DCM, ICM, and Network Models) to generate
a stacked data frame of all simulations (instead of row means across
simulations). This is a breaking change that may require updating old code.as.data.frame.netdx
function extracts the timed edgelists directly from
a netdx
object.get_nwstats
function now extracts data frames of network statistics from
both netdx
and netsim
objects.get_sims
.plot.netdx
and plot.netsim
.ncores
argument in netdx
to prevent over
parallelization of simulations.netdx
objects.act.rate.m2
for network models
in param.net
, as this is an unused parameter for built-in models.b.rate
; it is now a.rate
. Inputs of a b.rate
parameter yield a message and will automatically set a.rate
to the b.rate
value. This is a breaking change that may require updating old code.netdx
(when dynamic
is set to FALSE
) to smoothed rolling averages instead of the full MCMC trace.
The trace plots may be turned back on with sim.lines = TRUE
.netdx
now includes a new argument, sequential
, for static diagnostics
that mirrors the same argument from ergm::simulate.ergm
to simulate from
MCMC chains based on previous draws versus new draws.mutate_epi
output when new variable is a constant.ggplot2
from depend to import.identical
function causing some to
fail under alternative BLAS/LAPACK implementations.as.data.frame
methods for netsim
and icm
classes now allow creation of a
single data frame with epidemic outcomes across multiple simulations, where
previous only single individual simulations would be output. This is specified
with the sim = "all"
parameter when out = "vals"
. See the help page for
examples. This "tidy" data format allows for easier integration with external
plotting and analysis approaches, including ggplot2.geom_bands
is a new "geom" for use by ggplot2
to facilitate plotting of
simulation intervals given a specified lower and upper quantile set. Examples
of plotting ICM simulations are provided, and the same principle applies for
network models. As a result of this, ggplot2
was added as a depend.truncate_sims
is a new utility function that takes truncates the time series
of a netsim
or icm
class object at a specified time step. This truncation
will remove all epidemic output before that time step, and reset the control
settings to start at that time step. This is useful in our modeling workflows
when we need to remove a pre-intervention burnin period from the model
simulations.init.net
allows you to pass in a vector of backwards-looking infection times
for those initally infected at t_1 through the infTime.vector
parameter.
Combined with the status.vector
parameter, this provides users maximal control
over who is infected and for how long as initial conditions.discord_edgelist
function.status.rand
argument for init.net
and init.icm
that allowed
users to specify a random number of initially infected. Support for this got
too complex for a little (or never) used argument, and users interested in
randomly setting the initial number infected may control this more flexibly
with the status.vector
parameter.grid
argument to plot functions to overlay a grid on line plots.plot.netdx
examples in help file.verbose
default for network models to TRUE
(reverts change in
v1.3.0 specifically for network models).leg
argument name (to add default legends to plots) to legend
. Note
this is backwards-incompatible because of fuzzy matching with other function
arguments starting leg
; prior model code must be updated.control.dcm
, nsteps
may now be a vector of time steps or, as before, an
integer containing the number of time steps within a DCM simulation. For example,
control.dcm(..., nsteps = seq(1980, 2015, 1/12), ...)
for solve for monthly
outputs from a range of dates from 1980 to 2015.mutate_epi
for adding new variables to a epidemic simulation object now works
for all three model classes.param
, init
, and control
functions are now dual-classed as
lists as well as their native classes.new.mod
into control.dcm
, printing the control.dcm
object
no longer yields a warning and instead prints the function name.transco
to use the base
adjustcolor
function.NA
for the final
value, creating issues with analyzing those data. Those NA
s are replaced with
the penultimate value of that vector.dcm
, icm
, and netsim
objects to list "Variables"
together instead of dividing them into compartments, flows, and other.popfrac
default for plotting dcm
, icm
, and netsim
objects
to FALSE
. This avoids any problems when prevalences are already stored within
the model simulation.verbose
default for control functions to FALSE
.print.netsim
when sims
is mean
, min
, or `max.print.coefdiss
output.plot.netsim
dissolution_coefs
.mutate_epi
function inspired by the dplyr
package, to add
post-hoc summary statistic calculations to completed network simulations.
See the function help file for examples.get_degree
function that returns a vector of current
network degree for each person in a network.as.phylo.transmat
to fix issues with vertex exit times and to
now accept multiple seed vertices if multiple seeds are detected, returning
a list of phylo objects of class multiPhylo
following the convention of
ape::read.tree
.netsim
. This
only supports single-node frameworks currently, using the doParallel
package. Run models
in parallel by using the ncores
parameter in control.net
.as.phylo.transmat
function to construct the phylo tree with all
network vertices as phylo-tips and all transmissions as phylo nodes.plot.netsim
now correctly functions for diagnostic plots (type = "formation"
)
when summary statistics contain variable names with numeric values as suffixes.edapprox = FALSE
in the netest
function).netest
when models
were fit with the full STERGM method.depend
parameter to TRUE
in control.net
when user
passes in any new birth or death modules.ape
package and a transmission timeline from the ndtv
package. See the help
files for the as.phylo.transmat
and plot.transmat
functions.epiweb(class = "net")
. It is also hosted online
at http://statnet.shinyapps.io/epinet/get_sims
function is used to extract individual simulations from larger netsim
objects. This function has been updated to include a var
argument that allows
for automatic calculation of which simulation is closest to the mean across
all simulations for extraction.as.data.frame
method for icm
and
netsim
classes. This will provide a data frame of output corresponding to
defined quantiles across all simulations contained within a model object.plot.netsim
in cases where there
are NA
values in the epidemiological output.control.net
when type
is missing, and automatically
sets type
to "SI"
. This will impact extensions to EpiModel in the case
when the default transmission module is replaced.netdx
on calculating summary statistics from models with multiple
structural zeros for target statistics.status.rand
, which controls whether the number initially
infected in stochastic epidemic models, to FALSE
. This will ensure that
exactly the number specified in init.icm
and init.net
are matched in each
simulation.netsim_parallel
function from the package. See the EpiModelHPC
extension package at http://github.com/statnet/EpiModelHPC for running network
simulations in parallel.check_bip_degdist
now uses more tolerant checks of equality when comparing
bipartite mode statistics.dcm
function.netest
to improve
performance of fitting models.births.FUN
, from the dynamic workflow by setting the argument value for that
module to NULL
in the control.net
inputs.calc_eql
function now returns test statistics invisibly.plot.netsim
is now a separate method for epidemic plots (it was previously a function call
to plot.icm
), with function arguments and default settings more consistent
across plotting functions. There may be minor backwards incompatibility for some
epidemic plots. Network statistic plots in plot.netdx
and plot.netsim
now
use the same methods and share the same defaults. The defaults for these plots
will be to plot smoothed quantile bands (the IQR) and means of simulations
without the individual simulation lines. Any individual elements may be toggled
on or off as before.param.icm
and param.net
classes.dissolution
argument to netest
. This argument specified the right-
hand sided dissolution formula for temporal ERGMs. It was removed because this
formula was already specified in the dissolution_coefs
function, the output
of which is passed to netest
, thereby removing the duplication.as.data.frame
methods for stochastic models remove NA
from individual
simulations when calculating row means.verbose
parameter in netest
now correctly controls the model fitting
output level in the underlying ergm
and stergm
functions.merge.netsim
now correctly checks elements of two objects to be merged when
the classes of those elements may be of length greater than 1....
argument to epiweb
to pass additional arguments to shiny::runApp
.graphics
, grDevices
, stats
, and utils
packages as
required by CRAN.netsim_parallel
function has been deprecated. This
functionality has been replaced with model simulation functions within the
EpiModelHPC
extension package: https://github.com/statnet/EpiModelHPCepiweb
.calc_eql
, calculates whether a model of any class in EpiModel
has reached an equilibrium state over a defined time series. Equilibrium is
defined as the absolute value of the difference of the maximum prevalence and
minimum prevalence over a specified time series falling below a specified
threshold. For stochastic models, these values are calcualted based on the
mean of the individual time series simulations.netest
now includes a new argument, nonconv.error
, that will send the
function to an error state if the ERGM did not coverge after the specified
number of interations. The default is to allow for a nonconverged model fit
to be returned. Requiring an error may be helpful when running a number of
models in batch mode.dcm
function, there was an error in the calculation of flows (e.g., disease incidence
or number of deaths per unit time) when the models were integrated with methods
other than the "Euler" solution. Flows are now calculated correctly for all
numerical integration methods supported via the deSolve
package.netest
will now check to ensure that the formation and dissolution models are
in allignment (terms specified in the same order) and that dissolution model is
of proper forms (see v1.1.4 notes).dissolution_coefs
for examples.use.pids
in control.net
. See help("persistent.ids") in the networkDynamic
package for more background.births.net
module that set the default entrTime
and
exitTime
attributes twice for bipartite models (#205).xlab
and ylab
(#206).get_sims
extraction now outputs correct data when object contains single
simulation.skip.check
argument for control.net
is even more flexible, to allow
for passing different class elements into netsim
with original models.param.error
argument for merge.netsim
that allows bypassing the stop
error if the parameters and control settings from the two merged objects are
not identical.control.net
has new module.order
argument to provide control of the order
in which modules are evaluated within each time step. The default ordering is
maintained as explained in the updated help file.netsim_parallel
now returns the correct object if used for single simulations
or on single cores.plot.icm
removes NA values from the data when calculating ylim
and the
quantile bands.netest
now implements an improved "Edges Dissolution Approximation" via the
edapprox
argument.control.dcm
option dede
, which if true allows for delayed
differential equations to be passed into a new model solved with dcm
.netdx
to simulate static diagnostics from an ERGM, rather
than the temporal diagnostics (still the default). This will help better
diagnose poor dynamic model fit when using the edges dissolution approximation
(#175).netdx
, with the method
parameter, to plot boxplots of
the simulations against the target statistics. The default is still the line
plots (#191).netdx
objects, similar
to epidemic data plots: mean lines and quantile bands. Additional arguments
added to allow toggling of these along with individual simulation lines and
target lines.netdx
is updated, along with a new statistic for the percent
deviation between the simulation means and target statistics (#192).print.netsim
(#183).get_sims
will subset and extract entire simulations from netsim
objects with multiple simulations. A vector of simulation numbers may be
specified, or if set as "mean", the simulation with the infected prevalence
closest to the means across all simulations will be chosen.save.other
parameter in control.net
may now be merged with merge.netsim
(#185).plot
for ICMs and network models when the y
argument is specified (#188).deSolve
moved from import to depend (#194).netdx
, for the proportion of edges that
dissolve per time step, as another diagnostic for the dissolution model (#53).plot.netsim
now allow specifying "mean"
, "min"
, or
"max"
to plot the network at with the most average, maximum, and minumum
disease prevalence at the specified time step (#73).param.net
function has been updated with details (#65).param.sens
, that allows bypassing the default
behavior of evaluating parameters with length greater than 1 as sensitivity
analyses. This should be used for single-run models if passing in parameters
with arbitrary form.plot.netsim
fixed (#164).edges_correct
, now runs for any
dependent network simulations, not just if built-in vital dynamics modules are
called (#141).verbose.icm
function (#71).save.other
control
setting in control.net
are now printed as output in print.netsim
(#174).get_network
,
get_transmat
, and get_nwstats
) which extract the network objects,
transmission matrices, and data frame of network statistics from a completed
netsim
simulation. These functions also support extraction of network model
simulations with multiple networks (see API note).netsim
objects now has an argument, network, for
plotting network statistics and static networks (type = "formation"
and
"network"
, respectively) in simulations with multiple networks.mean.smooth
. If TRUE
, this
uses a lowess smoother on the outcome variables of interest. This is helpful
in visualization of low-count outcomes like disease incidence.netsim_parallel
function. Note that this is experimental and has not been
tested extensively across platforms, so bug reports are welcome. Two parallel
methods are supported: doParallel
for multiple cores on a single node, and
doMPI
for multiple cores across multiple nodes. The latter requires an MPI
installation on a linux-based cluster.netdx
also accepts a new ncores
argument, which will
run the diagnostic simulations and calculations on those simulations in
parallel on a specified number of cores (single node only).skip.check
, for the control settings in both ICM and
network model classes, which overrides the default error checking of
parameters, initial conditions, and control settings. This should only be used
for original models with new modules that may unnecessarily trigger a check
error.save.other
, for the control settings in network models,
which is a character vector of other elements from the master data list, dat
,
to save out in the simulation.start
, for the control settings in network models, which
is a starting time step to resume simulations. In this case, the x
argument
in netsim
is a previously saved netsim
object rather than a netest
object. The start
argument should be one integer higher than the nsteps
in
that earlier netsim
object. The nsteps
argument should now be the final
steps for the simulation. Note that this requires specifying
save.other = "attr"
in the control settings, as well as saving the networks.netdx
diagnostic simulations for computationally
intensive parts of the simulations.netest
now provides an output argument. When
using the edges dissolution approximation (edapprox = TRUE
), one may set
output to "sim"
to save a static simulation network instead of the ergm
object as an element of the netest
output. This is mainly for file size
efficiency.(0, 1, 2)
to character ("s", "i", "r")
. This changes little when running
the integrated models, and has greater implications for the API when editing
modules. But one change for integrated models is that the status vector passed
into the initial conditions functions must now be in this new format. This also
impacts the expansion of EpiModel for original models.zeromarg
argument has been removed from plot.netsim
for static network
plots (type = "network"
) to reduce potential issues with setting default
margins on plots. Now they must explicitly be set with standard par options.all
to dat
to prevent function name conflicts. Additionally, all
summary output is now stored within dat$epi
, whereas the previous location
was all$out
.edges_correct
and verbose.net
. The former performs the adjustment
to the edges coefficient for network models with population size changes, in
order to preserve the mean degree; for mass action epidemic models, for example,
one would not want this adjustment, so the module should be set to NULL in
control.net
. The latter performs the printing of simulation results to the
console. Both functions are now listed in the modules help file accessed by:
help(modules.net)
.param
, init
, and control
functions
altogether for original ICM and network models, because the definition of new
and replacement modules occurs within the control functions themselves. The
existing control functions should be used as a template if one is considering
replacing these parameterization functions.control.net
) by setting the argument for that module to NULL
. This
may be replaced in the future by a user-defined ordered vector of modules.x
argument in netsim may now be a list of netest
objects. This would be
used only if supplying new simulation modules that know how to process that
data structure. The motivation for this is to allow original models with
multiple networks simulated (e.g., a main partnership network and a casual
partnership network).epiweb
function). These apps now benefit from the more stable
parameterization functions.print
method for the param.net
class to handle parameters that
are lists or data frames.merge.netsim
now ignores any differences in the environment of the
nwstats.formula
control, previously preventing proper merging of some network
model simulations.Model parameterization for all model classes has been substantially revised to improve organization and ability for expansion. Whereas previous models required input of parameters directly into the main functions (now: dcm, icm, and netsim), now the parameters are input into three parameter-processing functions: param, init, and control. The param function sets the core epidemic parameters, the init function sets the initial conditions, and the control function specifies other model settings. These functions are class-specific, so each function has a .dcm, .icm, or .net suffix.
Modeling functions have been renamed for clarity and consistency:
Network models with independence between epidemic/demographic processes and network structures (independent models) were previously first simulated with epiNet.simNet, and then those pre-simulated networks were input to epiNet.simTrans. Now the network model simulation is all handled within the simulation function, netsim.
Network model diagnostics have been moved from within the network estimation process (netest) to their own function: netdx. The parameter names for running, printing, and plotting the results of these diagnostics have been updated for consistency. See ?netdx and related functions.
Internal model functions have been significantly revised to improve efficiency.
The dcm function can handle model functions, parameter sets, and initial conditions of arbitrary complexity. See the HTML vignette on this topic at: http://statnet.org/EpiModel/vignette/NewDCMs.html
Moved the package vignettes external to the package to reduce package size and build time. They are now available at the EpiModel homepage at: http://statnet.org/trac/wiki/EpiModel
The EpiModel package provides functions for building, solving, and plotting mathematical models of infectious disease.
See the main package help function ?EpiModel-package, and the EpiModel tutorials online at http://statnet.org/trac/wiki/EpiModel to get started.