A curated collection of tutorials for extending the EpiModel platform to model infectious disease dynamics over networks. Each example demonstrates how to build custom modules for stochastic network models using exponential random graph models (ERGMs), with fully annotated walkthroughs on the Gallery website.
EpiModel provides built-in SIS/SIR models out of the box, but its module API supports arbitrarily complex epidemic systems. The learning curve for writing custom modules can be steep, so these examples teach by example -- from adding a single compartment to multi-stage disease models with interventions and cost-effectiveness analysis. The examples are organized from beginner-friendly fundamentals through intermediate extensions to full applied disease models.
Fundamentals
| Example | Description |
|---|---|
| SEIR/SEIRS: Adding an Exposed State | Adding an exposed (latent) compartment to SIR, with optional waning immunity |
| SI with Vital Dynamics | SI with aging, births, deaths, and age-specific mortality |
Interventions
| Example | Description |
|---|---|
| SEIR with AON Vaccination | SEIR with all-or-nothing vaccination, vital dynamics, and herd immunity |
| SEIRS with Leaky Vaccination | SEIRS with leaky vaccination (reduced transmission probability) and vital dynamics |
| Test and Treat | SIS with screening and antibiotic treatment for bacterial STIs |
| Time-Varying Vaccination | SIR with phased, pulse, and reactive (prevalence-triggered) vaccination schedules |
| Contact Tracing | SEIR with cumulative-edgelist contact tracing for a COVID-like acute outbreak; quarantine on reached partners |
| Partner Notification | SIS partner notification for an endemic STI; PR vs EPT arms on the cumulative edgelist |
Intermediate Extensions
| Example | Description |
|---|---|
| Competing Strains | SIS with two pathogen strains differing in infectiousness and duration |
| Social Diffusion | SI framework repurposed for social diffusion with threshold and dose-response contagion |
| Behavioral Risk Compensation | SIR with within-infection contact reduction; shows how ignoring stage-specific behavior biases calibrated transmissibility and NPI projections |
Network Features
| Example | Description |
|---|---|
| Observed Network Data | Epidemics over observed (census) dynamic networks without ERGM estimation |
| Multilayer Networks | Multilayer networks with cross-layer dependency (e.g., main vs. casual partnerships) |
Full Disease Models
| Example | Description |
|---|---|
| HIV | HIV with acute/chronic/AIDS stages and antiretroviral therapy (ART) |
| Syphilis | Multi-stage syphilis with diagnosis, treatment, and recovery |
| RSV (Age-Stratified, Multilayer) | Age-stratified SEIR over a family + community multilayer network, with elderly vaccination, infant prophylaxis, and NPIs |
Advanced Extensions
| Example | Description |
|---|---|
| Cost-Effectiveness Analysis | SI with cost-effectiveness analysis: costs, QALYs, discounting, and ICERs |
Most examples contain model.R (network estimation and simulation), module-fx.R (custom module functions), and index.qmd (annotated tutorial on the website). The Multilayer Networks example is the exception: it has no module-fx.R because it uses EpiModel's built-in SI modules and focuses entirely on the multilayer network mechanics.
The recommended way to learn is through the Gallery website, which presents each example as an annotated tutorial with model diagrams, code walkthroughs, and output plots. Start with the Fundamentals section and work through the examples in order.
To run the code yourself:
- R >= 4.5
- EpiModel >= 2.6.0 (required by every example)
- networkDynamicData (required by the Observed Networks example)
- dampack (required by the Cost-Effectiveness Analysis example)
Install everything needed to run all examples in one step:
install.packages(c("EpiModel", "networkDynamicData", "dampack"))Or, if you only want to run a subset, EpiModel alone covers all but the two examples noted above. Each model script will stop with a clear message if a missing optional dependency is needed.
Clone the repository, then run any example from the project root:
source("examples/si-vital-dynamics/model.R")Or from the command line:
Rscript examples/si-vital-dynamics/model.Rbash test.shThis runs each example's model.R and reports pass/fail with timing.
Contributions of new gallery examples are welcome! To contribute:
- Fork this repository on GitHub.
- Create a new subdirectory under
examples/named descriptively (e.g.,sir-vaccination/) containing:model.R-- main script for network estimation and simulationmodule-fx.R-- custom module functions plugged intocontrol.net()(omit if your example uses only EpiModel's built-in modules)index.qmd-- annotated Quarto tutorial (see existing examples for the format)thumbnail.png-- thumbnail image for the gallery listing
- Include the standard unit test lines near the top of
model.R(see existing examples). - Verify your example passes:
bash test.sh - Verify the website builds:
quarto render - Submit a Pull Request.
If using EpiModel for teaching or research, please include a citation:
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