epiworldR Workshop - Sunbelt 2025

library(epiworldR)

# Create a model
mymodel <- ModelSEIRCONN(
  name = "Nasty virus", 
  n = 10000, 
  prevalence = .001, 
  contact_rate = 4,
  transmission_rate = .4, 
  incubation_days = 7, 
  recovery_rate = 1/7
) |> verbose_off() 

# Add a second virus
add_virus(
  mymodel, 
  virus(
    name = "Nasty virus 2",
    prob_infecting = .5,
    recovery_rate = .3,
    ), 
  proportion = .001
)

# Rename the model
set_name(mymodel, mname = "SEIR COVID-19 model")

# Run the model
set.seed(8383)
run(mymodel, ndays = 100)

# Plot the model
# - Set graphical parameters to plot in 2x2 grid
op <- par(mfrow = c(2, 2), mar = par()$mar * c(1, 1, 1/2, 0))
# - Plot
plot(mymodel)
plot_reproductive_number(mymodel)
plot_incidence(mymodel)
plot_generation_time(mymodel)
# - Restore original graphical parameters
par(op)

Figure 1

Welcome to the Sunbelt 2025 workshop Simulating Complex Agent-Based Models with epiworldR.

The epiworldR R package is a wrapper of the C++ library epiworld. It provides a fast, highly customizable framework for building network-based transmission/diffusion agent-based models (ABM).

Key features of epiworldR include:

• Fast simulation with an average of 30 million agents/model-step/second
• Multi-disease models (e.g., competing pathogens, multiple rumors, etc.)
• Mutating pathogens
• User-defined interventions (events, tools, politices, etc.) that chagne model behavior while it’s running
• Adapting transmission and recovery rates based on comorbidities
• Parallel computing out-of-the-box
• Likelihood-Free Markhov chain Monte Carlo (LFMCMC)
• Coming Soon: Models with an arbitrary number of compartments/states beyond SIR/SEIR (available in the epiworld C++ library and currently being ported to R)

Additionally, while epiworldR was built for models of disease transmission, the epiworld framework is general enough to build models for any type of diffusion process (covered in Part 2a of this workshop).

Workshop Details

If you don’t want to use your personal computer, we have an online RStudio server available for you to use.¹

Schedule (Tentative)

• (10 min) Setup
• (50 min) Part 1: Basic Modeling
• (10 min) Break
• (30 min) Part 2a: Non-Disease Applications - Network Diffusion
• (30 min) Part 2b: Advanced Modeling - Multiple Diseases, Tools, and Events
• (10 min) Break
• (40 min) Part 3: Multiple Simulation Runs

Install epiworldR

You can install the latest stable version of epiworldR from CRAN:

install.packages("epiworldR")

or the latest development version from GitHub:

# install.packages("devtools")
devtools::install_github("UofUEpiBio/epiworldR")

Relevant Terminology

Agent-based modeling (ABM): A powerful computational approach that enables the simulation and analysis of complex systems by representing individual agents and their interactions within an environment. ABM provides a bottom-up perspective, allowing for the examination of emergent phenomena arising from the collective behavior of autonomous agents. By capturing the heterogeneity, autonomy, and adaptive nature of agents, ABM offers a versatile tool for investigating various domains, including social sciences, economics, biology, and epidemiology, offering valuable insights into the dynamics and patterns that emerge from the interactions of individual entities within a larger system.

As epiworldR focuses heavily on epidemiological applications, below are some common epidemiological terms that will be used throughout:

• SEIR, SIR, SIS, etc.: Epidemiological models used to analyze the spread and dynamics of diseases in a population. The models are named after the different compartments or states that an individual agent can fall into: Susceptible (S), Exposed (E), Infected (I), Recovered (R). So, SEIR has all four states, while SIR doesn’t have the Exposed state.
• SEIR connected (SEIRCONN), SIR connected (SIRCONN), etc.: Epidemiological models similar to their above counterparts (SEIR, SIR, etc.), but with the added assumption that each individual agent is connected to all other agents.
• Reproductive number: The average number of secondary transmissions from one infected person. For example, a reproductive number of 2.0 indicates that one infected person transmits the disease to two other people in the population on average.
• Incidence: The occurrence of new cases of disease or injury in a population over a specified period of time. In epiworldR each step of a model represents a “day”, thus epiworldR computes daily incidence.

About the Instructors

Andrew Pulsipher is a software developer and Dr. George G. Vega Yon is a Research Assistant Professor of Epidemiology, both at the University of Utah’s School of Medicine.

sir <- ModelSIR(
  name           = "COVID-19",
  prevalence     = .01,
  transmission_rate = .5,
  recovery_rate       = .5
  ) |>
    # Adding a Small world population 
    agents_smallworld(n = 500, k = 10, d = FALSE, p = .01) |>
    # Running the model for 50 days
    verbose_off() |>
    run(ndays = 50, seed = 1912)

## Transmission network
net <- get_transmissions(sir)

## Plotting
library(netplot)
library(igraph)
x <- graph_from_edgelist(as.matrix(net[,2:3]) + 1)

nplot(x, edge.curvature = 0, edge.color = "gray", skip.vertex=TRUE)

Figure 2: Example transmission network generated by epiworldR (plotted with netplot)

Footnotes

1. Please note that the online RStudio server and your data stored in it will be available for two weeks after the workshop. After that, the server will be shut down and all data will be deleted. If you would like to keep your data, please download it before the server is shut down.