Skip to content

Epidemic dynamics ​

Solve a susceptible–infectious–removed system and distinguish infectious prevalence from incident infections. The example is a synthetic prior-predictive scenario, inspired by the compartment structure in the Stan boarding-school case study. It does not use the case study's observed time series or estimate transmission parameters. Initial compartment counts, population size, output times and rate-prior parameters are explicit inputs in the source below. Time is measured in days, compartment sizes in people, and both rate constants in inverse days.

Differential equations ​

The susceptible compartment loses people through infection. That flow is proportional to the susceptible and infectious counts divided by the total population. The infectious compartment receives the same flow and loses people through removal. The removed compartment receives those removals. This closed system has no births, migration or return from removal to susceptibility. Adding the three derivatives therefore gives zero.

The right-hand side is a typed deterministic function defined with @deffun. Its signature identifies time, the state vector and shared rate inputs. The function returns a derivative vector with one entry per compartment. The model passes that function and the initial state to Stan's Runge–Kutta solver, then returns the trajectory at the requested output times.

julia
using StanBlocks

@deffun sir_rhs(t::real, state::vector[3], infection_rate::real,
                removal_rate::real, population::real)::vector[3] = begin
    susceptible = state[1]
    infectious = state[2]
    new_infections = infection_rate * susceptible * infectious / population
    removals = removal_rate * infectious
    derivative::vector[3]
    derivative[1] = -new_infections
    derivative[2] = new_infections - removals
    derivative[3] = removals
    derivative
end

sir_data = (;
    initial = [762.0, 1.0, 0.0], population = 763.0,
    times = collect(0.5:0.5:20.0), start = 0.0,
    log_infection_location = log(2.0), log_removal_location = log(0.4),
    log_rate_sd = 0.2,
)
const sir = @slic begin
    infection_rate ~ lognormal(log_infection_location, log_rate_sd)
    removal_rate ~ lognormal(log_removal_location, log_rate_sd)
    trajectory = ode_rk45(sir_rhs, initial, start, to_array_1d(times),
                          infection_rate, removal_rate, population)
    return trajectory
end
model = sir(; sir_data...)

Generated Stan ​

stan
functions {
vector sir_rhs(
    real t,
    vector state,
    real infection_rate,
    real removal_rate,
    real population
) {
    real susceptible = state[1];
    real infectious = state[2];
    real new_infections = ((infection_rate * susceptible * infectious) / population);
    real removals = (removal_rate * infectious);
    vector[3] derivative;
    derivative[1] = (-new_infections);
    derivative[2] = (new_infections - removals);
    derivative[3] = removals;
    return derivative;
}
}
data {
    real log_infection_location;
    real log_rate_sd;
    real log_removal_location;
    int times_n;
    int initial_n;
    vector[initial_n] initial;
    real start;
    vector[times_n] times;
    real population;
}
transformed data {
}
parameters {
}
transformed parameters {
}
model {
}
generated quantities {
    real infection_rate = lognormal_rng(log_infection_location, log_rate_sd);
    real removal_rate = lognormal_rng(log_removal_location, log_rate_sd);
    array[times_n] vector[initial_n] trajectory = ode_rk45(sir_rhs, initial, start, to_array_1d(times), infection_rate, removal_rate, population);
    array[times_n] vector[initial_n] MODEL_RV = trajectory;
}

The generated Stan program exposes both the function definition and the solver call. Reading them together checks that the same population and rates reach every evaluation of the derivative. The functions guide explains typed function definitions. The execution guide shows how the compiled model is evaluated through BridgeStan.

The model gives both rates lognormal priors and has no observations or likelihood. StanBlocks therefore draws the rates in generated quantities and evaluates the trajectory conditional on those draws. The build uses a fixed seed and displays one prior-predictive scenario. It is useful for checking units, state ordering and observation definitions before adding a likelihood. One scenario does not summarize the uncertainty induced by the prior distributions.

Run ​

The build evaluates the compiled model with an explicit RNG seed and extracts the rates and trajectory using the model descriptor and BridgeStan output names. The requested output times determine the points displayed on this page. They do not force the numerical solver to use those times as its internal integration steps; the solver chooses its own steps to meet its numerical tolerances.

QuantityValue
Infection rate (per day)1.82
Removal rate (per day)0.334
Reproduction number at full susceptibility5.455
Mean infectious period (days)2.997
Largest sampled prevalence (people)385.5
Time of largest sampled prevalence (days)5.5

The reproduction number reported here is the drawn infection-rate constant divided by the removal-rate constant. That ratio describes invasion into a fully susceptible population under this system's assumptions. The effective ratio later in the scenario also depends on the susceptible fraction. The mean infectious period is the reciprocal removal rate, corresponding to the constant individual removal hazard implied by the compartment equations.

The largest sampled prevalence is a property of the evaluated output grid. Its reported time is therefore the time of the largest displayed value, not an independently optimized continuous-time peak. Using a finer output grid could change that reported time without changing the differential equations. The table keeps those quantities separate from the drawn rates so that a numerical summary is not presented as an estimated biological parameter.

Diagnostics ​

Conservation of population provides a direct check on the solver result and on how its output is reshaped. At every output time, the sum of the susceptible, infectious and removed compartments should equal the initial population up to numerical error. The model also implies nonnegative compartment sizes and a susceptible count that does not increase.

CheckResult
Maximum population residual (people)5.68e-13
Minimum compartment count (people)0.2473
Susceptible count never increasestrue

These checks would detect several common implementation mistakes, including a sign error in a flow, swapped state indices or a reshaping error in the output. The conservation residual is expressed in people. It is an invariant check, not an estimate of the solver's total trajectory error: a numerically inaccurate trajectory can still conserve population. For an application that requires tighter numerical accuracy, vary solver tolerances and compare the result at the same output times.

There are no chain diagnostics because this example draws directly from its priors. There is also no comparison with observed infections, so it offers no empirical estimate of goodness of fit. These limitations are part of the model shown, rather than missing results to be supplied by interpreting its smooth trajectory as evidence.

Observation definitions ​

Prevalence is the number of people currently infectious at a particular time. Incidence counts transitions into infection over an interval. In this closed system, interval incidence equals the decrease in susceptible count between the interval's endpoints. The build calculates that difference directly from the trajectory, including the initial state for the first interval.

The curves refer to different quantities even though both are expressed as numbers of people. The blue value is a count at an instant. The orange value is a count accumulated during the preceding output interval. Changing the interval length changes the scale of the incidence curve; it does not change what infectious prevalence means. A rate of new infections would instead divide the interval count by its duration and would have units of people per day.

Choosing a likelihood requires matching its expected value to the recorded measurement. Daily newly reported cases do not directly observe the infectious compartment. Counts of people infectious at a survey time do not directly observe the decrease in susceptibility over a day. Reporting delays, ascertainment and overdispersion may require additional assumptions even after the appropriate state or flow has been selected.

A statistical extension can attach an observation distribution to the relevant trajectory quantity and bind observed outcomes. The deterministic function remains reusable, while the rates become inference parameters through their likelihood contributions. The composition guide explains how to separate reusable components, and the prediction guide explains how observed outcomes become replicated outcomes. Any such extension needs its own data provenance, numerical checks and predictive assessment.

Reproduce

Build calculation; no fitted parameters or cached draws. Source SHA-256: d3a0b8465c1ae02db62250159c9d8a55296ac84f522ee481bd559bec8780110a. Numerical receipt.

Source · Instructions

The shell command below reproduces this result from the repository root. It runs the documentation examples and regenerates the figure.

sh
julia --project=docs docs/make.jl