44  EpiModel Gallery Lab

The EpiModel Gallery is a library of worked examples, each one a self-contained extension of EpiModel for a specific disease, intervention, or modeling tool. It is where you go to find a starting point close to your own research question and adapt it, rather than build from a blank file.

This lab is the hands-on counterpart to the tutorial. In small groups you will take one Gallery example, run it, and take it apart with the structured worksheet below, then report back to the full group. The goal is the practical skill you will use most often after this course: reading, running, and reusing an extension somebody else wrote.

44.1 Setup

We will walk through these three steps together before splitting into groups. It is all done in RStudio, with a single line typed in the Console to remove one file.

1. Get the Gallery onto your machine. The easy, no-Git way: open the Gallery repository on GitHub, click the green Code button, and choose Download ZIP. Unzip it (double-click on macOS; right-click and “Extract All” on Windows), which gives a folder named EpiModel-Gallery-main. Move it somewhere you will find again, such as your Desktop. (If you already use Git you can clone the repository instead; you get the same files.) Each example is a folder inside, under examples/<slug>/, holding a model.R (network estimation plus epidemic run), a module-fx.R (the custom module functions), and the rendered index.qmd page you can read alongside the code.

2. Open the project, then switch off its renv so R uses your Module 0 packages. Double-click EpiModel-Gallery.Rproj to open the folder as a project in RStudio. This sets your working directory to the folder root automatically, which is where the scripts expect to run.

The Gallery ships as its own renv project: a file named .Rprofile switches R to an empty, project-private package library, so library(EpiModel) fails and rebuilding that library means compiling packages from source (slow, and needs Rtools on Windows). You already installed EpiModel and everything it needs in Module 0, so you just need to turn renv off. When the project opens you may see a message mentioning renv; ignore it and do not run renv::restore(). Instead, delete the activation file by typing this one line in the Console:

file.remove(".Rprofile")

Then restart the R session with Session → Restart R (or quit and reopen RStudio). With .Rprofile gone, R loads packages from the library Module 0 populated, and library(EpiModel) works. You only do this once per download. (Prefer not to type it? In the Files pane, bottom-right, click More ▸ Show Hidden Files, tick the box next to .Rprofile, click Delete, then Session → Restart R.)

3. Run on one core while you explore. Open an example’s model.R in the editor (File → Open File). Near the top is a block that sets the simulation size:

if (interactive()) {
  nsims  <- 5
  ncores <- 5
  nsteps <- 800
}

Five cores runs the five simulations in parallel, which is fine for a final run but breaks interactive debugging: browser() and debug() cannot reach code running inside the parallel worker processes, and you will see confusing messages if you try. Before you step through a module in browser mode (worksheet item 5), change both to 1:

  nsims  <- 1
  ncores <- 1

Leave the defaults for a plain run where you just want the epidemic plot; drop to 1 the moment you want to debug. This is the same convention as the tutorial, which ran on one core and one simulation to step through the infection module, then raised both for the full run.

44.2 Step 1: Choose an example

Pick one example that is close to a disease, intervention, or method your group cares about. The catalog spans several kinds of extension; a curated cut:

Aim to include at least one non-STI system among the group’s picks (for example the SEIR/SEIRS respiratory model, the age-stratified RSV model, or the SI vital-dynamics example). A recurring question in this course is where network modeling applies beyond sexually transmitted infections, and these examples answer it directly; if you are choosing freely, lean toward one of them.

Building blocks (start here if unsure)

• SEIR/SEIRS: Adding an Exposed State — a latent compartment and waning immunity.
• SI with Age-Specific Vital Dynamics — births, deaths, and aging on a life table.

Interventions

• Test and Treat for an SIS Epidemic — screening, diagnosis, and treatment.
• SEIR with Contact Tracing — partner tracing over the network.
• Partner Notification for an Endemic STI — notifying and treating recent partners.
• SIR with Time-Varying (Phased) Vaccination — a vaccination campaign that turns on and off over time.

Full disease models

• HIV with Care Cascade and PrEP — disease stages, ART, and prevention.
• Age-Stratified RSV on a Multilayer Network — a non-STI respiratory model with age structure and NPIs.
• Syphilis Progression Model — multi-stage natural history.

The full catalog has more; browse it if none of the above fits.

44.3 Step 2: Run it and take it apart

Opening the project (Setup step 2) already set your working directory to the folder root, which is where the scripts have to run. Open the example’s model.R in the editor and click the Source button in the editor toolbar, or run source("examples/<slug>/model.R") in the console. This runs from the folder root, which is required: every model.R loads its module functions with a path written relative to that root, such as source("examples/seir-exposed-state/module-fx.R"). Sourcing from inside the example folder, or copying the two scripts somewhere on their own, will fail at that line. Confirm you get a plotted epidemic, then answer this worksheet for your example.

NoteWorksheet

1. Research question. What disease, intervention, or method is this example about, and what question would you use it to answer?
2. Compartments and attributes. What disease states does it track beyond S/I, and what nodal attributes does it add (age, treatment status, risk group, …)? Where are those attributes set?
3. The modules. For each custom function in module-fx.R, write the three-part API summary from the tutorial: what it reads off dat, what it does, what it writes back.
4. One knob. Pick a single parameter, predict what raising or lowering it will do to the epidemic, change it, re-run, and check your prediction.
5. Extend it. Open the example’s own “Next Steps” section on its Gallery page. Pick one of the suggested extensions, or one of your own (you are not limited to the list), and sketch how you would build it: which module or modules you would change, what attributes or parameters you would add, and what each would read, do, and write. Attempt it in code if you have time.
6. Cross-disease transfer. Name one mechanism in this example that would carry over to a very different disease, one thing that would have to be reparameterized or restructured to model that disease, and whether a dyadic (partnership) network is the right contact structure for it, or why not.

44.4 Step 3: Debrief

Each group gives a two-minute tour of its example: the research question, the one or two modules that make it distinctive, what the parameter change showed, and the extension it sketched from the example’s Next Steps. As a full group, look across the examples for the shared pattern: nearly every extension is a small set of custom modules that read attributes, apply a stochastic process, and write updated attributes back, over a network EpiModel keeps re-simulating. That pattern, not any single example, is what you take away.