Contagion Lab

Contagion Lab simulates how a disease spreads through a population. The package compares three types of model. The compartment model uses SEIR equations over time. The stochastic compartment model uses the same equations with random variation. The agent based model runs on a contact network. The package plots the case curves for all models. The package writes a report with the parameters and results.

This is a learning and analysis tool. It is not a substitute for public health software.

Value

The package answers one question. How do the modeling approaches differ?

Compartment models are fast and smooth. Stochastic models add random variation to the smooth curve. Agent models show discrete individuals and random variation. Use the package to compare curves, add interventions, and fit parameters.

Features

• Run an SEIR compartment model over time.
• Run a stochastic SEIR compartment model over time.
• Run a small agent based model on a contact network.
• Plot the case curves for all models.
• Add vaccination and distancing interventions.
• Fit model parameters from a case count series.
• Write a Markdown report with parameters and results.

Architecture

The package has six modules.

Module	File	Role
Parameters	R/params.R	Build and check parameter sets.
Compartment model	R/seir.R	Integrate the SEIR equations with RK4.
Stochastic model	R/stochastic.R	Draw daily transitions with random steps.
Agent model	R/agent.R	Simulate agents on a contact network.
Fitting	R/fit.R	Estimate parameters from case data.
Plot and report	R/plot.R, R/report.R	Draw curves and write reports.

All models return the same data layout. Each run returns a data frame with seven columns. The columns are time, susceptible, exposed, infectious, recovered, cumulative_cases, and cases. The cases column holds daily incidence.

The compartment model uses a fixed step Runge-Kutta integrator. The stochastic model draws each day from binomial distributions. The agent model uses daily steps and a fixed random seed. All models are deterministic for a fixed seed.

Setup

Install R version 3.6 or later. Install the package dependencies.

install.packages(c("testthat", "ggplot2"))

Install the package from the repository root.

R CMD INSTALL .

Load the package.

library(contagionlab)

Quick start

Run all three models with matching parameters.

result <- run_comparison(
  seir_params(N = 10000, beta = 0.45, sigma = 1 / 2, gamma = 1 / 6,
              init_exposed = 10, duration = 90),
  agent_params(N = 2000, degree = 10, transmission_prob = 0.1,
               latent_days = 2, infectious_days = 6,
               init_exposed = 10, duration = 90, seed = 42),
  stochastic_params = stoch_params(N = 10000, beta = 0.45,
                                   sigma = 1 / 2, gamma = 1 / 6,
                                   init_exposed = 10,
                                   duration = 90, seed = 42)
)

View the summary metrics.

result$metrics

Plot the case curves.

plot_case_curves(result)

Write a report.

write_report(result, path = "report.md")

The examples directory has two full scripts. Run them from the package root.

Rscript inst/examples/compare.R
Rscript inst/examples/fit.R

The compare script writes a report and a plot. The fit script estimates parameters from the bundled case series.

Sample output

Run the quick start commands. The metrics table shows the following values.

model	peak cases	peak day	total cases	final susceptible	final infectious	outbreak end
compartment	384.8	39	9137.4	852.6	29.5	90
stochastic	393	44	9348	642	66	90
agent	98	27	1986	4	0	51

The figure shows all three case curves.

The compartment curve peaks later and higher than the agent curve. The stochastic curve tracks the compartment curve with random noise. The agent curve peaks earlier and lower. The differences come from the model structure, not the parameters.

Fit the bundled case series.

fit <- fit_seir(flu_cases$cases, N = 10000)
fit$beta

The fit returns the known values. The fitted beta is 0.45. The fitted gamma is 0.1667. The fitted initial exposed count is 10.

Interventions

Add a vaccination campaign on day 30.

params <- seir_params(beta = 0.5, duration = 90,
  interventions = list(
    vaccination(time = 30, coverage = 0.5, efficacy = 0.9)))

Add distancing from day 30.

params <- seir_params(beta = 0.5, duration = 90,
  interventions = list(
    distancing(time = 30, effect = 0.5)))

The same intervention objects work for every model.

Testing

Run the deterministic test suite.

Rscript -e 'testthat::test_local()'

The suite covers the compartment model, the stochastic model, the agent model, the interventions, the fitting, the plots, and the report. All tests pass in this release.

Roadmap

The stochastic compartment model is complete. Later releases add one feature at a time.

• Add a fitted comparison against real epidemic data.
• Add more intervention options, such as quarantine.
• Add a basic spatial contact network.

Limitations

The agent model uses a fixed latent period and a fixed infectious period. Real infections vary between people. The compartment model assumes a well mixed population. The stochastic model draws whole group counts each day. It does not track individual people. The contact network is a small world model, not a real contact graph. The fitted parameters depend on the initial exposed count. The package does not model births, deaths, or waning immunity.

Test status

The package passes R CMD check with no warnings or errors. The continuous integration runs on Linux, macOS, and Windows. The workflows in .github/workflows run on push and pull request. The CI results appear on the Actions page of the repository.

License

MIT License. See LICENSE and LICENSE.md.