epimodel / epimodel-gallery Goto Github PK

Gallery of Network-Based Epidemic Model Templates for EpiModel

License: MIT License

R 99.67% Shell 0.33%

epimodel-gallery's Introduction

EpiModel

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 easy application programming interface (API) for extending these templates to address novel scientific research aims.

Lead Authors


Samuel M. Jenness	Department of Epidemiology	Emory University
Steven M. Goodreau	Department of Anthropology	University of Washington
Martina Morris	Departments of Statistics and Sociology	University of Washington
Adrien Le Guillou	Department of Epidemiology	Emory University
Chad Klumb	Center for Studies in Demography and Ecology	University of Washington

Additional contributors to EpiModel are listed on the contributors page.

Installation

The current release version can be found on CRAN and installed with:

install.packages("EpiModel", dependencies = TRUE)

To install this development version, use the remotes package:

if (!require("remotes")) install.packages("remotes")
remotes::install_github("EpiModel/EpiModel")

Documentation and Support

Website. The main website for EpiModel, with tutorials and other supporting files, is here: http://www.epimodel.org/.

Methods Paper. A good place to start learning about EpiModel is the main methods paper published in the Journal of Statistical Software. It is available at: https://doi.org/10.18637/jss.v084.i08.

Summer Course. Network Modeling for Epidemics is our annual 5-day course at the University of Washington where we teach the statistical theory, software tools, and applied modeling methods using EpiModel. Our course materials are open-source and updated annually around the time of the course.

Getting Help. Users are encouraged to use Github issues on this repository as a place to ask questions (both technical coding questions and conceptual modeling questions), report bugs, and request new features & functionality. Broader modeling questions can be posted on the Discussions board here.

The EpiModel Gallery

The EpiModel Gallery contains templates of extensions to EpiModel, for now focused on network-based mathematical modeling class. We will be continuing to add new examples the gallery, and encourage users to either file requests for new examples or else to contribute them directly.

Citation

If using EpiModel for teaching or research, please include a citation our main methods paper:

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

Please also send us an email if you have used EpiModel in your work so we can add the citation below.

Funding

The primary support for the development of these software tools and statistical methods has been by two National Institutes of Health (NIH) grants. Our applied research projects using EpiModel have received funding from the NIH and Centers for Disease Control and Prevention (CDC). Our team also receives institutional support through center-level NIH grants. A full list of our funding support can be found here.

EpiModel in the Scientific Literature

EpiModel and its extension packages have been used in the following scientific journal articles. A list of these articles can be accessed in a wiki page or on Zotero. (If you are aware of others, send us an email at [email protected] to be included in this list.)

Copyright

These materials are distributed under the GPL-3 license, with the following copyright and attribution requirements listed in the LICENSE document above.

epimodel-gallery's People

Contributors

Stargazers

Watchers

epimodel-gallery's Issues

Basic syphilis model

This model would include the natural history of syphilis (an extension SEIRS) in a MSM population, with the first iteration not including testing and treatment, and perhaps a second iteration doing so.

Show how to use new start argument to restart simulation

Existing Examples to Port Over

SEIR (Ebola) model from NME
Using observed network data in census form (from epimodel.org gallery)

Please clarify cloning vs. forking for contributions

The README file uses the term "cloning" in the How to Use section, and "forking" in the Contributions section. It might help to explicitly use the term forking throughout, as cloning (for those of us with EpiModel-Gallery repo push access) can lead to commits without pull requests.

Gallery visuals

It would be great if the gallery were really a gallery -- with visuals and brief descriptions of each example. Maybe a website landing page like https://shiny.rstudio.com/gallery/ ? And a wiki for FAQ and other info? Could be built up over time...

Multiple edge-type networks example

For example, simple interacting main + casual networks

Simple Templates

One mode SI
Two mode SIS with nodematch for dissortative mixing and group-specific infection probabilities and recovery rates

Social contagion/diffusion model

The process of idea/norm transmission does not depend on simple connection between one I and one S but multiple I connected to S. i.e., Transmission probability is a function of current degree.

End-horizon simulation speed with parameter updater

For the CEA gallery, pull request #33 incorporates the new parameter updater changes to EpiModel to handle the end horizon, while pull request #34 reflects the code before these changes. On my PC, executing the first netsim with the old code (1 core, 104 steps, 10 sims) takes 2.379 minutes. The updated version is sleeker in terms of the code, but the first netsim takes 1 minute longer at 3.376 min. In the clunky original set-up, the sim speeds up significantly during the end horizon but the same does not occur in the updated version of code.
@AdrienLeGuillou
@smjenness
#33
#34

Compartment Model - Hospital Acquire Infections

There is a lot of interest currently in how infection outbreaks occur in localized environment, and the different transmission modes that result in infection. It would be great to see an example use of EpiModel that includes non-human compartments, such as this common framework for a health care environment:

If EpiModel has already been extended this way, it would be great to build off of that template.

Custom initialization modules

With the update to the Gallery Examples to be inline with EpiModel2.0, I noticed that a lot of the bespoke modules (particularly infection modules) placed initialization of attributes within the actual epidemic modules. For example, in the CompetingStrains gallery example, strain attribute is initialized in the recovery.FUN = recov.2strains:

recov.2strains <- function(dat, at) {
  ##  ----------------------- ##
  if (at == 2) {
    nActive <- length(active)
    strain <- rep(NA, nActive)
    strain[idsInf] <- rbinom(nElig, 1, pct.st2) + 1  # Strains are labeled 1 and 2
    dat <- set_attr(dat, "strain", strain)
  ## ------------------------ ##
  }

This is not neccessarrily an issue in this case, however, because of the new behavior of the control.net parameter type, other more commonly used attributes - such as infTime - also need to be moved into these modules.

Would it make more sense to have a separate init.FUN = init_model to handle this initialization step to both make the code cleaner and more flexible (module.order must be explicitly stated which may not match the intended epidemic progression of the example) as well as makingit clear to the end user how their own code should be set up?

Add timing to each test file in test.sh

@AdrienLeGuillou : could we calculate the script timing (for each folder) directly in the test.sh script and output after each "OK" line?

Remove all references to nw object in Gallery examples

For example:
https://github.com/EpiModel/EpiModel-Gallery/blob/master/2018-08-SIwithVitalDynamics/module-fx.R#L16-L20
https://github.com/EpiModel/EpiModel-Gallery/blob/master/2018-08-SIwithVitalDynamics/module-fx.R#L26

There may be others that I have not found. These dynamic updates to the nw object are both unnecessary (because they should be handled in nwupdate.net), and produce errors, when the model with run with tergmLite = TRUE (because there is no dat$nw object in this case.

Set up Travis CI to run through all examples

Here's an example travis.yml file that runs a specific script:
https://github.com/hadley/adv-r/blob/master/.travis.yml

Vaccination model

Could follow two examples of all-or-nothing and leaky vaccine

example of clustering for network models

For example, people are clustered in households, which are clustered in neighborhoods, and there is a strong propensity for in-household mixing, a slightly weaker propensity for in-neighborhood mixing, and a zero propensity for cross-neighborhood mixing.

nw <- network.initialize(100, directed = FALSE)

hh <- rep(1:4, each = 25)
nb <- rep(1:2, each = 50)

nw %v% "hh" <- hh
nw %v% "nb" <- nb

fit <- ergm(nw ~ edges + nodemix("nb", base = c(1,3)),
            target.stats = c(50, 0))
sim <- simulate(fit, nsim = 1e4, statsonly = TRUE,
                monitor = ~nodemix("nb", base = 0)+nodemix("hh", base = 0))
colMeans(sim)

EpiModel Gallery Example: Empty Discordant Edgelist

EpiModel Gallery examples have been updated to take advantage of the changes to vital dynamics in EpiModel workflow. However, running through the examples, specifically "SEIR with All or Nothing Vaccine", has issues with empty discordant edgelists, that are not present when using base epimodel functions. The error occurs (using the SEIR example) here within the infect extension module:

      del$transProb <- inf.prob
      del$actRate <- act.rate
      del$finalProb <- 1 - (1 - del$transProb)^del$actRate

Because the discordant edgelist has no rows (and is not null) this causes an error. Adding this change to the conditional logic:

    if (!(is.null(del)) && nrow(del) > 0) {

Solves this error. However I can not replicate this with base EpiModel and can not see why this is occurring. Any help or a second set of eyes on this would be appreciated. For reproduciability I'm using a seed of 123.

"2018-08-ObservedNetworkData" not working with EpiModel 2.1

This model fails with error:

A ERROR occured in module 'resim_nets.FUN' at step 2: 
	Error in get_control(dat, "isTERGM"): There is no control value called `isTERGM` in the control list of the Master list object (dat)

simply adding isTERGM = TRUE or isTERGM = FALSE to the control object does not solve the problem. This problem only exists with EpiModel 2.1 and not 2.0.5

Basic HIV model

Syphilis Model: Timing of Progression to Primary Stage

Currently, any active node in the incubating stage of syphilis infection is eligible for progression to the primary stage (Line 136 of module-fx.R reads idsEligPri <- which(active == 1 & syph.stage == 1)). Since the infection function is called before the disease progression function, this means that it's possible for a node to become infected and immediately progress from the incubating to the primary stage within the same time step.

Changing Line 136 to idsEligPri <- which(active == 1 & syph.stage == 1 & infTime < at) would ensure that there is at least a one time step delay between infection and progression to the primary stage.

this needs to just be:

source("module-fx.R", echo = TRUE)

You can change the local working directory with setwd, use the drop down menu (session -> set working directory -> source file location), or use an Rstudio Project file.