Model features • EpiNow2

This vignette provides a quick reference to the modelling features available in EpiNow2. For an overview of how these models connect see the model overview. For mathematical details see the model definition vignettes (infection model, secondary model, truncation model). For applied examples see the options vignette. For prior guidance see the prior choice guide.

Component overview

The package’s modelling features fall into four groups.

Estimation models fit a Stan model to data:

Infection model — estimate_infections()
Secondary model — estimate_secondary()
Truncation / nowcasting — estimate_truncation()
Delay distribution fitting — estimate_dist()

Model configuration controls how the estimation models behave:

Reproduction number — rt_opts()
Gaussian process — gp_opts()
Delay distributions — gt_opts(), delay_opts(), trunc_opts()
Observation model — obs_opts()
Options summary — defaults and which models use each

Forward simulation and forecasting generate observations:

Simulation — simulate_infections(), simulate_secondary()
Forecasting — forecast_infections(), forecast_secondary()

Supporting utilities:

Data preprocessing — fill_missing()
Workflow wrappers — epinow(), regional_epinow()
Stan backend — stan_opts()

Estimation models

Infection model

estimate_infections() reconstructs infections from a count time series (e.g. reported cases) using either a generative renewal model or non-parametric back-calculation.

Feature	Argument	Description	See also
Renewal equation (default)	`rt = rt_opts(...)`	Generative model using the reproduction number and generation time	Model definition
Back-calculation	`rt = NULL`, `backcalc = backcalc_opts(...)`	Non-parametric deconvolution of reported cases	Model definition

Secondary model

estimate_secondary() estimates the relationship between a primary and secondary observation (e.g. cases and deaths, admissions and bed occupancy).

Feature	Argument	Description	See also
Incidence model	`secondary_opts(type = "incidence")`	Secondary reports as a convolution of primary cases	Secondary model definition
Prevalence model	`secondary_opts(type = "prevalence")`	Cumulative secondary reports (e.g. bed occupancy)	Secondary model definition

Truncation / nowcasting

Recent observations are typically incomplete due to reporting delays (right truncation). estimate_truncation() estimates a truncation distribution from multiple snapshots of the same data source over time and produces a nowcast (predicted complete observations). The reconstructed observations can be obtained from the fit with get_predictions(). The estimated distribution can be passed to estimate_infections() via trunc_opts() for truncation-adjusted inference.

Feature	Argument	Description	See also
Estimate truncation and nowcast	`estimate_truncation(data = list_of_snapshots)`	Fit a truncation distribution and produce a nowcast from data snapshots	Truncation model definition
Truncation-adjusted inference	`estimate_infections(truncation = trunc_opts(dist = ...))`	Adjust for right-truncation of recent data in the observation model	Truncation model definition

Delay distribution fitting

estimate_dist() fits delay distributions from linelist data using likelihood functions vendored from primarycensored.

Feature	Argument	Description	See also
Double interval censoring	Date columns in linelist	Accounts for censoring of both primary and secondary events	Fitting delays
Variable censoring windows	`pdate_upr`, `sdate_upr` columns	Per-observation primary and secondary censoring window widths	Fitting delays
Right truncation	`obs_date` column	Per-observation truncation times from reporting delays	Fitting delays
Primary event distribution	`estimate_dist(primary = "expgrowth")`	Account for exponential growth in primary events	Fitting delays
Distribution families	`estimate_dist(dist = ...)`	`"lognormal"` (default), `"gamma"`, `"normal"`, `"exp"`	Fitting delays
Observation aggregation	Automatic	Identical delay-censoring-truncation strata are aggregated to speed up fitting	Fitting delays

Model configuration

Reproduction number

When using the renewal equation, several options control how the time-varying reproduction number is modelled.

Feature	Argument	Description	See also
GP on differences of log Rt (default)	`rt_opts(gp_on = "R_t-1")`	Gaussian process applied to successive Rt values	Options examples
GP on deviations from R0	`rt_opts(gp_on = "R0")`	Gaussian process applied as deviations from a global mean	Options examples
Random walk	`rt_opts(rw = 7)` with `gp = NULL`	Piecewise-constant Rt with specified step size	Options examples
Breakpoints	Add a `breakpoint` column to the input data	Step changes in Rt at user-specified dates; on by default in `rt_opts()`, set `use_breakpoints = FALSE` to disable	Options examples
Fixed Rt	`gp = NULL` (and default `rt_opts()`)	Constant reproduction number sampled from the prior; no GP, no random walk	Options examples
Population adjustment	`rt_opts(pop = Fixed(N))`	Adjust Rt for susceptible depletion; `pop` accepts any `<dist_spec>`	Options examples
Growth rate method	`rt_opts(growth_method = "infectiousness")`	Alternative growth rate calculation via infectiousness	Model definition

Gaussian process

The Gaussian process controls the flexibility of the time-varying reproduction number or infection trajectory. Configured via gp_opts(). For kernel mathematics and the Hilbert space spectral approximation see the GP implementation details vignette.

Feature	Argument	Description
Kernel choice	`gp_opts(kernel = ...)`	`"matern"` (default), `"se"`, `"ou"`, or `"periodic"`
Disable GP	`gp = NULL` in `estimate_infections()`	Remove the Gaussian process entirely
Accuracy/speed tradeoff	`gp_opts(basis_prop = ...)`	Higher values increase accuracy; lower values are faster (default 0.2)

Delay distributions

Delay distributions map latent infections to observed quantities. See the workflow vignette for a practical guide and the prior choice guide for default priors.

Feature	Argument	Description
Generation time	`gt_opts(dist = ...)`	Time between successive infections
Reporting delay	`delay_opts(dist = ...)`	Delay from infection to report
Composite delays	`delay_opts(dist = dist1 + dist2)`	Sum of independent delay distributions
Non-parametric delays	`dist = NonParametric(...)`	Fixed PMF rather than a parametric family
Uncertain parameters	e.g. `LogNormal(meanlog = Normal(...), ...)`	Parameters drawn from prior distributions
Truncation correction	`trunc_opts(dist = ...)`	Adjust for right-truncation of recent data

Observation model

The observation model links latent expected cases to reported data. Configured via obs_opts(). For default prior values see the prior choice guide.

Feature	Argument	Description
Negative binomial (default)	`obs_opts(family = "negbin")`	Overdispersed count model
Poisson	`obs_opts(family = "poisson")`	No overdispersion
Day-of-week effect	`obs_opts(week_effect = TRUE)`	Separate reporting rate per day of the week (default on)
Scaling / ascertainment	`obs_opts(scale = Normal(...))`	Fraction of infections observed; accepts any `<dist_spec>`
Likelihood weighting	`obs_opts(weight = ...)`	Re-weight observations in the log density
Aggregated data	`fill_missing(missing_dates = "accumulate")`	Latent daily expectations are accumulated in the model before likelihood evaluation
Missing observations	NA values in data	Time points with NA observations are excluded from the likelihood

Aggregation and missing data are handled at the model level in Stan, not just in preprocessing. fill_missing() constructs the flags that the Stan model uses; the model itself accumulates latent expected reports and drops missing observations from the likelihood. Both estimate_infections() and estimate_secondary() support these features.

Options summary

The table below summarises the options functions, what they configure, their defaults, and which estimation functions use them.

Function	Configures	Default	Used by
`rt_opts()`	Reproduction number model	GP on log Rt differences	`estimate_infections()`
`gp_opts()`	Gaussian process prior	Matern 3/2 kernel	`estimate_infections()`
`gt_opts()`	Generation time distribution	`Fixed(1)` (degenerate 1-day generation interval; users normally override)	`estimate_infections()`
`delay_opts()`	Reporting delay distributions	`Fixed(0)` (no delay)	`estimate_infections()`, `estimate_secondary()`
`obs_opts()`	Observation model	Negative binomial with day-of-week effect	`estimate_infections()`, `estimate_secondary()`
`trunc_opts()`	Truncation distribution	`Fixed(0)` (no truncation)	`estimate_infections()`
`backcalc_opts()`	Back-calculation settings	Smoothed reports as prior	`estimate_infections()` (when `rt = NULL`)
`secondary_opts()`	Secondary model type	Incidence	`estimate_secondary()`

See the prior choice guide for default values and guidance.

Forward simulation and forecasting

The estimation models already produce forecasts as part of their fit, projecting forward over a horizon set by the horizon argument. The functions below are for the cases where you want to simulate or forecast separately from a fit: generating synthetic observations from known parameters, or extending a fitted model with new inputs (e.g. a new Rt trajectory or new primary data).

Simulation

Simulation functions generate observations from known or fixed parameters, useful for model checking and scenario analysis.

Feature	Argument	Description	See also
Simulate infections	`simulate_infections(R, initial_infections)`	Forward-simulate from a given Rt trajectory via the renewal equation	Workflow
Simulate secondary	`simulate_secondary(primary, ...)`	Simulate secondary observations from primary data	Secondary model definition
Convolve and scale	`convolve_and_scale(data, ...)`	R-based convolution with time-varying parameters	Secondary model definition

Forecasting

Forecasts can be generated from fitted models by projecting forward with specified or estimated parameters.

Feature	Argument	Description	See also
Infection forecast	`forecast_infections(estimates, R)`	Simulate future infections from a fitted model with a new Rt trajectory	Workflow
Secondary forecast	`forecast_secondary(estimate, primary)`	Forecast secondary observations from new primary data	Secondary model definition

Supporting utilities

Data preprocessing

fill_missing() is an R-side utility that prepares data for the estimation functions by constructing the accumulation and missingness flags that the Stan models require.

Feature	Argument	Description
Accumulate missing dates	`fill_missing(missing_dates = "accumulate")`	Mark missing dates for model-level accumulation
Zero-fill missing dates	`fill_missing(missing_dates = "zero")`	Insert zero observations for missing dates
Ignore missing dates (default)	`fill_missing(missing_dates = "ignore")`	Skip missing dates in the likelihood
Handle NA observations	`fill_missing(missing_obs = ...)`	Accumulate or zero-fill NA values
Weekly reporting	`fill_missing(initial_accumulate = 7)`	Set accumulation window for weekly data

Workflow wrappers

Convenience functions wrap the core estimation and reporting steps.

Feature	Argument	Description	See also
Production wrapper	`epinow()`	Wraps `estimate_infections()` with logging and formatted output	epinow vignette
Multi-region	`regional_epinow()`	Runs `epinow()` across regions in parallel	Getting started
Region-specific options	`opts_list()`	Generate per-region configuration lists	Getting started

Stan backend

Models are implemented in Stan. Users can switch between MCMC sampling (default, via cmdstanr or rstan), variational inference, the Laplace approximation, or pathfinder using stan_opts(method = ...). See the workflow vignette for details on configuring the backend.