Tools for simulating mathematical models of infectious disease dynamics. Epidemic model classes include deterministic compartmental models, stochastic agent-based 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 easy API for extending these templates to address novel scientific research aims.
identicalfunction causing some to fail under alternative BLAS/LAPACK implementations.
icmclasses 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_bandsis a new "geom" for use by
ggplot2to 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,
ggplot2was added as a depend.
truncate_simsis a new utility function that takes truncates the time series of a
icmclass 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.netallows you to pass in a vector of backwards-looking infection times for those initally infected at t_1 through the
infTime.vectorparameter. Combined with the
status.vectorparameter, this provides users maximal control over who is infected and for how long as initial conditions.
init.icmthat 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
gridargument to plot functions to overlay a grid on line plots.
plot.netdxexamples in help file.
verbosedefault for network models to
TRUE(reverts change in v1.3.0 specifically for network models).
legargument 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.
nstepsmay 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_epifor adding new variables to a epidemic simulation object now works for all three model classes.
controlfunctions are now dual-classed as lists as well as their native classes.
control.dcm, printing the
control.dcmobject no longer yields a warning and instead prints the function name.
transcoto use the base
NAfor the final value, creating issues with analyzing those data. Those
NAs are replaced with the penultimate value of that vector.
netsimobjects to list "Variables" together instead of dividing them into compartments, flows, and other.
popfracdefault for plotting
FALSE. This avoids any problems when prevalences are already stored within the model simulation.
verbosedefault for control functions to
min, or `max.
mutate_epifunction inspired by the
dplyrpackage, to add post-hoc summary statistic calculations to completed network simulations. See the function help file for examples.
get_degreefunction that returns a vector of current network degree for each person in a network.
as.phylo.transmatto 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
multiPhylofollowing the convention of
netsim. This only supports single-node frameworks currently, using the
doParallelpackage. Run models in parallel by using the
as.phylo.transmatfunction to construct the phylo tree with all network vertices as phylo-tips and all transmissions as phylo nodes.
plot.netsimnow correctly functions for diagnostic plots (
type = "formation") when summary statistics contain variable names with numeric values as suffixes.
edapprox = FALSEin the
netestwhen models were fit with the full STERGM method.
control.netwhen user passes in any new birth or death modules.
apepackage and a transmission timeline from the
ndtvpackage. See the help files for the
epiweb(class = "net"). It is also hosted online at http://statnet.shinyapps.io/epinet/
get_simsfunction is used to extract individual simulations from larger
netsimobjects. This function has been updated to include a
varargument that allows for automatic calculation of which simulation is closest to the mean across all simulations for extraction.
netsimclasses. This will provide a data frame of output corresponding to defined quantiles across all simulations contained within a model object.
plot.netsimin cases where there are
NAvalues in the epidemiological output.
typeis missing, and automatically sets
"SI". This will impact extensions to EpiModel in the case when the default transmission module is replaced.
netdxon 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.netare matched in each simulation.
netsim_parallelfunction from the package. See the EpiModelHPC extension package at http://github.com/statnet/EpiModelHPC for running network simulations in parallel.
check_bip_degdistnow uses more tolerant checks of equality when comparing bipartite mode statistics.
netestto improve performance of fitting models.
births.FUN, from the dynamic workflow by setting the argument value for that module to
calc_eqlfunction now returns test statistics invisibly.
plot.netsimis 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.netsimnow 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.
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_coefsfunction, the output of which is passed to
netest, thereby removing the duplication.
as.data.framemethods for stochastic models remove
NAfrom individual simulations when calculating row means.
netestnow correctly controls the model fitting output level in the underlying
merge.netsimnow correctly checks elements of two objects to be merged when the classes of those elements may be of length greater than 1.
epiwebto pass additional arguments to
utilspackages as required by CRAN.
netsim_parallelfunction has been deprecated. This functionality has been replaced with model simulation functions within the
EpiModelHPCextension package: https://github.com/statnet/EpiModelHPC
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.
netestnow 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.
dcmfunction, 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
netestwill 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).
control.net. See help("persistent.ids") in the
networkDynamicpackage for more background.
births.netmodule that set the default
exitTimeattributes twice for bipartite models (#205).
get_simsextraction now outputs correct data when object contains single simulation.
control.netis even more flexible, to allow for passing different class elements into
netsimwith original models.
merge.netsimthat allows bypassing the stop error if the parameters and control settings from the two merged objects are not identical.
module.orderargument 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_parallelnow returns the correct object if used for single simulations or on single cores.
plot.icmremoves NA values from the data when calculating
ylimand the quantile bands.
netestnow implements an improved "Edges Dissolution Approximation" via the
dede, which if true allows for delayed differential equations to be passed into a new model solved with
netdxto 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
methodparameter, to plot boxplots of the simulations against the target statistics. The default is still the line plots (#191).
netdxobjects, 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.
netdxis updated, along with a new statistic for the percent deviation between the simulation means and target statistics (#192).
get_simswill subset and extract entire simulations from
netsimobjects 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.
control.netmay now be merged with
plotfor ICMs and network models when the
yargument is specified (#188).
deSolvemoved 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.netsimnow allow specifying
"max"to plot the network at with the most average, maximum, and minumum disease prevalence at the specified time step (#73).
param.netfunction 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.
edges_correct, now runs for any dependent network simulations, not just if built-in vital dynamics modules are called (#141).
save.othercontrol setting in
control.netare now printed as output in
get_nwstats) which extract the network objects, transmission matrices, and data frame of network statistics from a completed
netsimsimulation. These functions also support extraction of network model simulations with multiple networks (see API note).
netsimobjects now has an argument, network, for plotting network statistics and static networks (
type = "formation"and
"network", respectively) in simulations with multiple networks.
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_parallelfunction. Note that this is experimental and has not been tested extensively across platforms, so bug reports are welcome. Two parallel methods are supported:
doParallelfor multiple cores on a single node, and
doMPIfor multiple cores across multiple nodes. The latter requires an MPI installation on a linux-based cluster.
netdxalso accepts a new
ncoresargument, 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
netsimis a previously saved
netsimobject rather than a
startargument should be one integer higher than the
nstepsin that earlier
nstepsargument 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.
netdxdiagnostic simulations for computationally intensive parts of the simulations.
netestnow 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
ergmobject as an element of the
netestoutput. This is mainly for file size efficiency.
USER INTERFACE CHANGES
(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.
zeromargargument has been removed from
plot.netsimfor 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.
datto prevent function name conflicts. Additionally, all summary output is now stored within
dat$epi, whereas the previous location was
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:
controlfunctions 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.
xargument in netsim may now be a list of
netestobjects. 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).
epiwebfunction). These apps now benefit from the more stable parameterization functions.
param.netclass to handle parameters that are lists or data frames.
merge.netsimnow ignores any differences in the environment of the
nwstats.formulacontrol, 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.