26 Introduction

An epidemic curve tells you how many people were infected and when. It cannot tell you how the infection moved: which contacts carried it, which parts of the network it reached and which it never touched, or how the network’s own changes opened and closed paths as the epidemic ran. This module is about seeing that. We use dynamic network visualization, animated movies of an epidemic spreading over a network that is itself changing, as an instrument for understanding how contact structure shapes transmission.

The movies are the tool, not the object. What we are really doing is taking the network features you have been specifying as abstract numbers, a mean degree, a partnership duration, a clustering target, and watching what each one does to an epidemic, one contact at a time. A target statistic on a page and a movie of the epidemic it produces are the same fact in two forms, and pairing them is how this module builds intuition for the machinery you assembled in Modules 1 through 4.

The module sits at a hinge in the course. Modules 1 through 3 built a statistical model for a contact network; Module 4 put an epidemic on top of one and ran it end to end. Here we open that machinery up and watch it work, while the population is still closed and the moving parts are few enough to see all at once. Module 7 then adds an open population, where people enter and leave.

26.1 How the Tutorials Are Built

The tutorials share the same path, worth naming because the habit is as much the point as any one movie:

Observe a baseline epidemic running on a network.
Predict what one change to the network specification should do, before you run it.
Animate that change and watch the mechanism.
Diagnose with netdx that the network model actually hit the target you set, so that anything you see is due to the network you specified rather than one that quietly missed.
Compare replicated outcomes: a single movie shows a mechanism, but to claim a change made the epidemic larger or smaller we compare the average over many runs.

Not every step recurs in every tutorial: the first builds and diagnoses the whole pipeline in full, and the later ones lean on that baseline, adding the predict-and-compare habit as they change the specification. That last step is important enough to earn its own caveat.

One movie is a demonstration, not a measurement

Every movie in this module is built from a single simulation of a small network (100 nodes) over a short horizon (25 steps). That is the opposite of Module 4’s advice, and the difference is deliberate.

Estimating an epidemic outcome, incidence or prevalence over time, needs large networks, long horizons, and many hundreds of simulations, so that the averages and their spread are stable. A visualization needs a network small enough to see. So the movies demonstrate mechanisms; they do not measure effects.

Be blunt about the consequence: each movie is one draw. Where we say one specification spreads faster or slower than another, that is a claim about the average over many runs, and any single movie can and sometimes will show the opposite. So the tutorials that make directional claims pair their movies with a short replicated-run comparison. Read the movie for how the mechanism works, and the replicated numbers for how big it is.

26.2 The EpiModel Pipeline, End to End

Module 4 walked each of these functions in depth. This is the map rather than the tour: what hands what to what, and what type comes back. Tutorial 1 is a complete instantiation of it, and the later tutorials change one row of this table at a time.

Step	Function	Consumes	Produces
Set up the population	`network_initialize()`	a size	an empty `network`
Describe who forms ties	a formation formula + `target.stats`	ERGM terms and a target for each	a specification, not yet a fit
Describe how ties end	`dissolution_coefs()`	mean durations	offset coefficients on the logit scale
Fit the network model	`netest()`	all of the above	a `netest` object
Check the fit	`netdx()`	a `netest` object	simulated statistics against their targets
Set the epidemic	`param.net()`, `init.net()`, `control.net()`	rates, seeds, settings	three parameter objects
Run the epidemic	`netsim()`	a `netest` object + the three	a `netsim` object
Look at it	`get_network()`, `get_transmat()`, `render.d3movie()`	a `netsim` object (`get_network`, `get_transmat`); the `networkDynamic` from `get_network` (`render.d3movie`)	networks, transmission trees, movies

The one thing to carry into Module 7: the network model and the epidemic model are fit and run separately. netest never sees a disease, and netsim never re-estimates a network. Everything Module 7 adds, people arriving and departing, lands on the seam between those two.

26.3 The Two Limiting Cases You Already Know

Two of the specifications ahead are extremes of a single dial, partnership duration, and each one reproduces a modeling tradition you may already know. The mapping is worth getting straight now, because it is easy to reverse:

Partnerships that last a single time step are torn down and redrawn fresh every step. Contact becomes effectively instantaneous and memoryless, which is close to what a compartmental (ODE) model assumes: $\beta S I / N$ has no partnerships in it, only a contact rate. (This is the rapid-mixing limit an ODE describes, made precise in the duration tutorial.)
Partnerships that never end freeze the contact network into one fixed graph for the whole epidemic, which is exactly what a static network model assumes: configuration models, percolation (the study of when one large connected cluster appears in a fixed random graph), and the classic threshold results.

Between those two extremes lies everything a real contact process actually does. The point of this module, and of the framework generally, is that duration is a parameter you set, not an assumption baked into your choice of model class. You can sit anywhere on the dial, and reproduce either endpoint on purpose, as a comparison. (An optional appendix, after the lab, develops this into a single organizing idea, the network’s clock against the epidemic’s, for anyone who wants to go further.)

26.4 What Is in This Module

Three tutorials and a lab, building up one network feature at a time over the same 100-node population with the same epidemic parameters. Only the network specification changes.

Building an Epidemic Movie is the baseline and the reference implementation. It walks the whole EpiModel pipeline once, from an empty network through estimation, diagnosis, simulation, and animation, and teaches how to read a movie. It closes with an optional look at transmission trees, the static who-infected-whom views.

Concurrency and Duration turns to the two features of network timing that matter most for spread: whether partnerships overlap (concurrency) and how long they last (duration). This is where the two limiting cases above appear as models you build on purpose.

Clustering and Heterogeneity adds local clustering (triangles) and then lets contact patterns and partnership durations depend on who people are, building the most complex model in the course one term at a time.

Lab is your turn: a menu of paths to explore, changing one thing, predicting, and re-running.

An optional Appendix: How Fast Is the Network? follows the lab. It steps outside the movie format, trading animations for diagnostics and small tables, to develop the module’s ideas into a single organizing question: how fast the network turns over relative to the epidemic. Read it if you are curious how the pieces fit together; nothing later in the course depends on it.

26.5 Module Learning Objectives

Extract dynamic network data from an EpiModel object, and describe what a networkDynamic object carries that a static network does not.
Generate a dynamic network animation, and recognize the qualitative signature of a formation model’s targets (density, concurrency, clustering, assortative mixing) in the movie they produce.
Explain why a single small simulation demonstrates a mechanism but cannot measure an effect, and back a directional claim with replicated runs.
Reproduce, on purpose, what a compartmental model and a static network model each assume about contact, as the two extremes of partnership duration.
Reason about duration relative to both the model time step and the infectious period.
Explain why local clustering (triangles, via gwesp) tends to slow spread by concentrating contacts among people the infection has already reached.
Make contact patterns depend on who people are, using nodal attributes (nodematch, nodefactor, absdiff), and anticipate which subgroups an infection reaches.
Specify a dissolution model in which relational duration varies by partnership type, and read the resulting coefficients and corrections back correctly.

# Introduction An epidemic curve tells you how many people were infected and when. It cannot tell you *how* the infection moved: which contacts carried it, which parts of the network it reached and which it never touched, or how the network's own changes opened and closed paths as the epidemic ran. This module is about seeing that. We use dynamic network visualization, animated movies of an epidemic spreading over a network that is itself changing, as an **instrument for understanding how contact structure shapes transmission**. The movies are the tool, not the object. What we are really doing is taking the network features you have been specifying as abstract numbers, a mean degree, a partnership duration, a clustering target, and watching what each one does to an epidemic, one contact at a time. A target statistic on a page and a movie of the epidemic it produces are the same fact in two forms, and pairing them is how this module builds intuition for the machinery you assembled in Modules 1 through 4. The module sits at a hinge in the course. Modules 1 through 3 built a statistical model for a contact network; Module 4 put an epidemic on top of one and ran it end to end. Here we open that machinery up and watch it work, while the population is still closed and the moving parts are few enough to see all at once. Module 7 then adds an open population, where people enter and leave. ## How the Tutorials Are Built The tutorials share the same path, worth naming because the habit is as much the point as any one movie: 1. **Observe** a baseline epidemic running on a network. 2. **Predict** what one change to the network specification should do, *before* you run it. 3. **Animate** that change and watch the mechanism. 4. **Diagnose** with `netdx` that the network model actually hit the target you set, so that anything you see is due to the network you specified rather than one that quietly missed. 5. **Compare replicated outcomes**: a single movie shows a *mechanism*, but to claim a change made the epidemic larger or smaller we compare the average over many runs. Not every step recurs in every tutorial: the first builds and diagnoses the whole pipeline in full, and the later ones lean on that baseline, adding the predict-and-compare habit as they change the specification. That last step is important enough to earn its own caveat. ::: {.callout-note .concept} ## One movie is a demonstration, not a measurement Every movie in this module is built from a **single** simulation of a **small** network (100 nodes) over a **short** horizon (25 steps). That is the opposite of Module 4's advice, and the difference is deliberate. Estimating an epidemic outcome, incidence or prevalence over time, needs large networks, long horizons, and many hundreds of simulations, so that the averages and their spread are stable. A visualization needs a network small enough to see. So the movies **demonstrate mechanisms**; they do not **measure effects**. Be blunt about the consequence: each movie is one draw. Where we say one specification spreads faster or slower than another, that is a claim about the average over many runs, and any single movie can and sometimes will show the opposite. So the tutorials that make directional claims pair their movies with a short replicated-run comparison. Read the movie for how the mechanism works, and the replicated numbers for how big it is. ::: ## The EpiModel Pipeline, End to End Module 4 walked each of these functions in depth. This is the map rather than the tour: what hands what to what, and what type comes back. Tutorial 1 is a complete instantiation of it, and the later tutorials change one row of this table at a time. | Step | Function | Consumes | Produces | |---|---|---|---| | Set up the population | `network_initialize()` | a size | an empty `network` | | Describe who forms ties | a formation formula + `target.stats` | ERGM terms and a target for each | a specification, not yet a fit | | Describe how ties end | `dissolution_coefs()` | mean durations | offset coefficients on the logit scale | | Fit the network model | `netest()` | all of the above | a `netest` object | | Check the fit | `netdx()` | a `netest` object | simulated statistics against their targets | | Set the epidemic | `param.net()`, `init.net()`, `control.net()` | rates, seeds, settings | three parameter objects | | Run the epidemic | `netsim()` | a `netest` object + the three | a `netsim` object | | Look at it | `get_network()`, `get_transmat()`, `render.d3movie()` | a `netsim` object (`get_network`, `get_transmat`); the `networkDynamic` from `get_network` (`render.d3movie`) | networks, transmission trees, movies | The one thing to carry into Module 7: the network model and the epidemic model are fit and run **separately**. `netest` never sees a disease, and `netsim` never re-estimates a network. Everything Module 7 adds, people arriving and departing, lands on the seam between those two. ## The Two Limiting Cases You Already Know Two of the specifications ahead are extremes of a single dial, partnership **duration**, and each one reproduces a modeling tradition you may already know. The mapping is worth getting straight now, because it is easy to reverse: - Partnerships that last a **single time step** are torn down and redrawn fresh every step. Contact becomes effectively instantaneous and memoryless, which is close to what a **compartmental (ODE) model** assumes: $\beta S I / N$ has no partnerships in it, only a contact rate. (This is the rapid-mixing limit an ODE describes, made precise in the [duration tutorial](mod5-Timing.html).) - Partnerships that **never end** freeze the contact network into one fixed graph for the whole epidemic, which is exactly what a **static network model** assumes: configuration models, percolation (the study of when one large connected cluster appears in a fixed random graph), and the classic threshold results. Between those two extremes lies everything a real contact process actually does. The point of this module, and of the framework generally, is that duration is a **parameter you set**, not an assumption baked into your choice of model class. You can sit anywhere on the dial, and reproduce either endpoint on purpose, as a comparison. (An [optional appendix](mod5-Timescale.html), after the lab, develops this into a single organizing idea, the network's clock against the epidemic's, for anyone who wants to go further.) ## What Is in This Module Three tutorials and a lab, building up one network feature at a time over the same 100-node population with the same epidemic parameters. Only the network specification changes. **[Building an Epidemic Movie](mod5-Movie.html)** is the baseline and the reference implementation. It walks the whole EpiModel pipeline once, from an empty network through estimation, diagnosis, simulation, and animation, and teaches how to read a movie. It closes with an optional look at transmission trees, the static who-infected-whom views. **[Concurrency and Duration](mod5-Timing.html)** turns to the two features of network *timing* that matter most for spread: whether partnerships overlap (concurrency) and how long they last (duration). This is where the two limiting cases above appear as models you build on purpose. **[Clustering and Heterogeneity](mod5-Structure.html)** adds local clustering (triangles) and then lets contact patterns and partnership durations depend on who people are, building the most complex model in the course one term at a time. **[Lab](mod5-Lab.html)** is your turn: a menu of paths to explore, changing one thing, predicting, and re-running. An optional **[Appendix: How Fast Is the Network?](mod5-Timescale.html)** follows the lab. It steps outside the movie format, trading animations for diagnostics and small tables, to develop the module's ideas into a single organizing question: how fast the network turns over relative to the epidemic. Read it if you are curious how the pieces fit together; nothing later in the course depends on it. ## Module Learning Objectives * Extract dynamic network data from an EpiModel object, and describe what a `networkDynamic` object carries that a static network does not. * Generate a dynamic network animation, and recognize the qualitative signature of a formation model's targets (density, concurrency, clustering, assortative mixing) in the movie they produce. * Explain why a single small simulation demonstrates a mechanism but cannot measure an effect, and back a directional claim with replicated runs. * Reproduce, on purpose, what a compartmental model and a static network model each assume about contact, as the two extremes of partnership duration. * Reason about duration relative to both the model time step and the infectious period. * Explain why local clustering (triangles, via `gwesp`) tends to slow spread by concentrating contacts among people the infection has already reached. * Make contact patterns depend on who people are, using nodal attributes (`nodematch`, `nodefactor`, `absdiff`), and anticipate which subgroups an infection reaches. * Specify a dissolution model in which relational duration varies by partnership type, and read the resulting coefficients and corrections back correctly.