EpiNova: Getting Started

Why EpiNova?

Feature eSIR EpiNova
Compartmental models SIR only SIR, SEIR, SEIRD, SVEIR, SVEIRD, age-SEIR
pi(t) shape Step / exponential Step, exponential, spline, GP, composite
Inference JAGS (external binary) MLE, SMC (pure R); HMC via Stan (optional)
Rt estimation No Built-in; EpiEstim wrapper (optional)
Spatial structure None Multi-patch + gravity mobility
Scenario comparison No plot_scenarios()
Forecast scoring No CRPS, coverage, MAE

Data

We use the Hubei Province COVID-19 data from January to February 2020.

NI_complete <- c(41, 41, 41, 45, 62, 131, 200, 270, 375, 444, 549,
                 729, 1052, 1423, 2714, 3554, 4903, 5806, 7153, 9074,
                 11177, 13522, 16678, 19665, 22112, 24953, 27100,
                 29631, 31728, 33366)
RI_complete <- c(1, 1, 7, 10, 14, 20, 25, 31, 34, 45, 55, 71, 94,
                 121, 152, 213, 252, 345, 417, 561, 650, 811, 1017,
                 1261, 1485, 1917, 2260, 2725, 3284, 3754)
N  <- 58.5e6
Y  <- NI_complete / N - RI_complete / N
R  <- RI_complete / N

1. SEIRD model with a smooth spline intervention

pi_spline <- build_pi_spline(
  knot_times  = c(0, 10, 22, 30, 60, 120),
  knot_values = c(1, 0.95, 0.60, 0.35, 0.25, 0.25)
)

params <- list(beta  = 0.35, gamma = 0.07, sigma = 0.20,
               delta = 0.005, I0 = Y[1],  E0 = Y[1] * 2)

init  <- c(S = 1 - params$E0 - params$I0,
           E = params$E0, I = params$I0, R = R[1], D = 0)
times <- 0:200

traj <- solve_model(params, init, times,
                    model = "SEIRD", pi_fn = pi_spline)

plot_trajectory(traj, obs_Y = Y, obs_R = R,
                T_obs_end = length(Y) - 1,
                title = "SEIRD + Spline pi(t) - Hubei Province")

2. Scenario comparison

pi_none   <- function(t) 1
pi_mild   <- build_pi_step(c(10), c(1, 0.6))
pi_strict <- build_pi_spline(c(0, 10, 22, 60), c(1, 0.9, 0.25, 0.35))

scenario_pis <- list(
  "No intervention" = pi_none,
  "Mild lockdown"   = pi_mild,
  "Strict lockdown" = pi_strict
)

sc_df <- do.call(rbind, lapply(names(scenario_pis), function(nm) {
  tr <- solve_model(params, init, times,
                    model = "SEIRD", pi_fn = scenario_pis[[nm]])
  data.frame(
    time     = tr$time,
    I_median = tr$I,
    I_lower  = tr$I * 0.75,
    I_upper  = tr$I * 1.25,
    scenario = nm
  )
}))

plot_scenarios(sc_df, obs_Y = Y)

3. Built-in Rt estimation (no extra packages needed)

new_cases <- pmax(0L, diff(NI_complete))
Rt_df     <- estimate_Rt_simple(new_cases, mean_si = 5.2,
                                 sd_si = 2.8, window = 7L)
plot_Rt(Rt_df, change_times = c(10, 22))

4. Composite NPI functions

lockdown <- build_pi_step(c(10, 60), c(1.0, 0.4, 0.65))
masks    <- build_pi_spline(c(0, 15, 30, 90), c(1, 0.92, 0.80, 0.80))
combined <- compose_pi(lockdown, masks)

traj_combined <- solve_model(params, init, times,
                              model = "SEIRD", pi_fn = combined)

plot_trajectory(traj_combined, obs_Y = Y, obs_R = R,
                T_obs_end = length(Y) - 1,
                title = "Composite NPI: lockdown x mask mandate")

5. Two-patch spatial model

M <- gravity_mobility(
  N_vec    = c(58.5e6, 1.4e9 - 58.5e6),
  dist_mat = matrix(c(0, 1000, 1000, 0), nrow = 2),
  kappa    = 1e-7,
  max_travel = 0.02
)

ode_fn <- build_multipatch_SEIR(
  n_patches  = 2,
  M          = M,
  beta_vec   = c(0.35, 0.25),
  gamma_vec  = c(0.07, 0.07),
  sigma_vec  = c(0.20, 0.20),
  pi_fn_list = list(pi_spline, build_pi_step(c(15), c(1, 0.5)))
)

init_mat <- matrix(
  c(1 - 1e-4, 1 - 1e-5, 1e-5, 5e-6, 1e-4, 1e-5, 0, 0),
  nrow = 2
)

mp_df <- solve_multipatch(ode_fn, init_mat,
                           times = 0:150, n_patches = 2)

plot_multipatch_snapshot(mp_df, t_snapshot = 30,
                          patch_names = c("Hubei", "Rest of China"))

6. Forecast scoring

holdout <- Y[20:30]
fc_df   <- data.frame(
  time     = 19:29,
  I_median = traj$I[20:30],
  I_lower  = traj$I[20:30] * 0.60,
  I_upper  = traj$I[20:30] * 1.40
)
score_forecast(fc_df, holdout)
##           CRPS coverage_95          MAE
## 1 0.0003226951           0 0.0003245607

Package philosophy

EpiNova is built on three principles absent from eSIR:

  1. Composability - interventions, models, and inference backends are independent building blocks.
  2. Modularity - no mandatory external binaries; optional packages unlock extra capabilities.
  3. Calibration accountability - every forecast can be scored with score_forecast().