---
title: 'EpiModel: Mathematical Modeling of Infectious Disease Dynamics'
author: "Samuel M. Jenness, Steven M. Goodreau, Martina Morris, and Adrien Le Guillou"
date: "`r Sys.Date()`"
vignette: >
  %\VignetteIndexEntry{EpiModel Introduction}
  \usepackage[utf8]{inputenc}
  %\VignetteEngine{knitr::rmarkdown}
editor_options:
  chunk_output_type: console
---

```{r, echo=FALSE}
vers <- packageVersion("EpiModel")
year <- format(Sys.time(), "%Y")
```

## What EpiModel Does

The **EpiModel** package provides tools for simulating mathematical models of infectious disease dynamics. It supports three model classes:

- **Deterministic Compartmental Models (DCMs):** ODE-based, population-level models for rapid exploration of epidemic dynamics under simplifying assumptions.
- **Stochastic Individual-Contact Models (ICMs):** Agent-based models with random mixing and stochastic variability.
- **Stochastic Network Models:** The primary focus of EpiModel. These use exponential-family random graph models (ERGMs) from the Statnet suite to represent dynamic contact networks where partnerships form, persist, and dissolve according to statistically estimated rules. Network models capture features that strongly influence transmission dynamics---degree distributions, partnership durations, concurrency, assortative mixing, and clustering.

All three model classes share a unified API: configure inputs with `param.*()`, `init.*()`, and `control.*()`, then run simulations with `dcm()`, `icm()`, or `netsim()`.

This vignette walks through the full network model pipeline, from network estimation through epidemic simulation and analysis.

## The Network Model Pipeline

### Step 1: Network Estimation

Network models begin with specifying and estimating the contact network. We define a network of 500 people, then estimate an ERGM that produces networks with a target mean degree of 0.7 (175 edges), limited concurrency (no more than 110 nodes with 2+ partners), and no one with 4+ partners. Partnerships last an average of 50 time steps.

```{r step1, results = "hide", message = FALSE}
library(EpiModel)
set.seed(12345)

nw <- network_initialize(n = 500)

formation <- ~edges + concurrent + degrange(from = 4)
target.stats <- c(175, 110, 0)
coef.diss <- dissolution_coefs(
  dissolution = ~offset(edges),
  duration = 50   # mean partnership duration in time steps
)

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

### Step 2: Network Diagnostics

Before using the estimated network in an epidemic model, we diagnose the fit. `netdx` simulates dynamic networks from the fitted model and compares summary statistics against targets. This is a critical validation step.

```{r step2, results = "hide"}
dx <- netdx(est, nsims = 5, nsteps = 500, verbose = FALSE)
```

The formation diagnostic shows how well the simulated networks maintain the target statistics (dashed lines) over time. The mean across simulations (solid line) and the interquartile range (shaded band) should track the targets closely:

```{r step2_plot1, fig.width = 8}
plot(dx)
```

The duration diagnostic confirms that partnership durations match the specified target of 50 time steps:

```{r step2_plot2}
plot(dx, type = "duration")
```

### Step 3: Epidemic Simulation

With a validated network model, we layer on the epidemic. This SIS model uses a per-act transmission probability of 0.4, 2 acts per partnership per time step, and a recovery rate of 0.05. We seed 10 infections and run 5 stochastic simulations for 500 time steps.

```{r step3, results = "hide"}
param <- param.net(inf.prob = 0.4, act.rate = 2, rec.rate = 0.05)
init <- init.net(i.num = 10)
control <- control.net(type = "SIS", nsims = 5, nsteps = 500, verbose = FALSE)

sim <- netsim(est, param, init, control)
```

### Step 4: Analyzing Results

#### Epidemic Trajectories

The default plot shows compartment sizes over time, with the mean across simulations (solid line), individual simulation traces, and a shaded interquartile range capturing stochastic variability:

```{r step4_epi, fig.width = 8}
plot(sim, sim.lines = TRUE, sim.alpha = 0.3,
     mean.lwd = 3, qnts = 0.5, main = "SIS Epidemic on a Dynamic Network")
```

For prevalence (proportions rather than counts), use `popfrac = TRUE`:

```{r step4_prev}
plot(sim, y = "i.num", popfrac = TRUE, sim.lines = TRUE, sim.alpha = 0.3,
     mean.lwd = 3, qnts = 0.5, main = "Infection Prevalence",
     ylab = "Prevalence", legend = FALSE)
```

#### Summary Statistics

`summary` reports means, standard deviations, and proportions across simulations at a specified time step:

```{r step4_summary}
summary(sim, at = 500)
```

#### Data Extraction

All epidemic data can be extracted as a `data.frame` for custom analysis---per-simulation values, means, or standard deviations across simulations:

```{r step4_df}
d <- as.data.frame(sim)
head(d)
```

#### Transmission Trees

The transmission matrix records every infection event: who infected whom, when, and with what probability. This can be converted into a phylogenetic tree to visualize chains of transmission.

```{r step4_transmat}
# Run a separate SI model seeded with a single infection for a cleaner tree
set.seed(42)
param2 <- param.net(inf.prob = 0.5, act.rate = 2)
init2 <- init.net(i.num = 5)
control2 <- control.net(type = "SI", nsims = 1, nsteps = 60, verbose = FALSE)
sim2 <- netsim(est, param2, init2, control2)

tm <- get_transmat(sim2)
head(tm)
```

```{r step4_tree, fig.width = 8, fig.height = 5}
tmPhylo <- as.phylo.transmat(tm)
par(mar = c(2, 1, 2, 1))
plot(tmPhylo, show.node.label = TRUE, root.edge = TRUE, cex = 0.5,
     main = "Transmission Tree")
```

Each tip is an infected person; each internal node (labeled with the infector's ID) is a transmission event. The horizontal axis shows time, revealing when and how the epidemic branched through the network.


## Extending EpiModel

The built-in SI, SIR, and SIS models are starting points. EpiModel's extension API allows you to define custom models with arbitrary disease states, demographics, interventions, and feedback between the epidemic and the network. A custom module is simply a function that takes the simulation state (`dat`) and current time step (`at`), modifies state, and returns it:

```{r extension, eval = FALSE}
# Example: a custom progression module for an SEIR model
progress_module <- function(dat, at) {
  active <- get_attr(dat, "active")
  status <- get_attr(dat, "status")

  # E -> I transition
  ids.EtoI <- which(active == 1 & status == "e" & runif(length(status)) < 0.1)
  status[ids.EtoI] <- "i"

  # I -> R transition
  ids.ItoR <- which(active == 1 & status == "i" & runif(length(status)) < 0.02)
  status[ids.ItoR] <- "r"

  dat <- set_attr(dat, "status", status)
  dat <- set_epi(dat, "ei.flow", at, length(ids.EtoI))
  dat <- set_epi(dat, "ir.flow", at, length(ids.ItoR))
  return(dat)
}
```

Custom modules are passed to `control.net` and integrated into the simulation loop. The [EpiModel Gallery](https://epimodel.github.io/EpiModel-Gallery/) provides a library of worked extension examples, and the advanced vignettes in this package document the full API.

## Learning Pathway

We recommend the following tiered sequence for learning EpiModel, consistent with the learning pathway on the [EpiModel website](https://www.epimodel.org). This is oriented towards those interested in stochastic network models, the primary focus of EpiModel.

### Beginner

- **Intro to EpiModel vignette:** This vignette and the full [package documentation](https://epimodel.github.io/EpiModel/) provide an overview of the three model classes and the unified API (core functions: `netest`, `netdx`, `netsim`).
- **JSS methods paper:** Our primary reference, published in the *Journal of Statistical Software*, provides the mathematical and computational foundations for all three model classes. See citation below.
- **NME Course, Section I (Chapters 3--35):** Lecture slides and tutorials covering network science, ERGM specification, model diagnostics, and built-in epidemic models (<https://epimodel.github.io/sismid/>).

### Intermediate

- **NME Course, Section II (Chapters 36--49):** [Extending EpiModel](https://epimodel.github.io/sismid/9_extending/mod9-Intro.html) materials covering the extension API for building custom models with novel disease states, demographics, and interventions.
- **EpiModel Gallery:** A library of worked extension model templates demonstrating custom disease states, demographics, interventions, and multi-layer networks (<https://epimodel.github.io/EpiModel-Gallery/>).

### Advanced

- **Package vignettes:** These vignettes within the package cover specific topics for users building custom network models with the extension API:
    - *Working with Model Parameters:* Scenarios for time-varying parameters, parameter input via tables, and random parameter distributions for sensitivity analysis.
    - *Working with Custom Attributes and Summary Statistics:* Nodal attributes, attribute histories, epidemic trackers, and custom summary statistics.
    - *Working with Network Objects:* Accessing and manipulating network objects, edgelists, cumulative edgelists, and reachability analysis within custom modules.
- **EpiModelHPC & slurmworkflow:** Tools for running large-scale simulations on high-performance computing clusters.
- **Template repositories:** [EpiModelHIV](https://github.com/EpiModel/EpiModelHIV) and [EpiModelCOVID](https://github.com/EpiModel/EpiModelCOVID) provide full-scale research model implementations.

## Package Documentation

The current version of EpiModel is v`r vers`. Within the package, consult the help documentation for each exported function:

```{r, eval=FALSE}
help(package = "EpiModel")
```

To see the latest updates, consult the `NEWS` file in the package or our GitHub Releases (<https://github.com/EpiModel/EpiModel/releases>).

## Getting Help

Technical coding questions, conceptual modeling questions, and feature requests may be posted as GitHub issues at our main repository (<https://github.com/EpiModel/EpiModel/issues>).

## Citation

If using EpiModel for teaching or research, please include a citation to our primary 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 (<https://doi.org/10.18637/jss.v084.i08>).
