# Model features

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, distribution model). For applied examples see the options vignette. For prior guidance see the prior choice guide.

# 1 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()`

# 2 Estimation models

## 2.1 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

See also: estimate_infections workflow

## 2.2 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

See also: estimate_secondary model definition

## 2.3 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

See also: estimate_truncation model definition

## 2.4 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 | Distribution model
Variable censoring windows | `pdate_upr`, `sdate_upr` columns | Per-observation primary and secondary censoring window widths | Distribution model
Right truncation | `obs_date` column | Per-observation truncation times from reporting delays | Distribution model
Primary event distribution | `estimate_dist(primary = "expgrowth")` | Account for exponential growth in primary events | Distribution model
Distribution families | `estimate_dist(dist = ...)` | `"lognormal"` (default), `"gamma"`, `"normal"`, `"exp"`, `"weibull"` | Distribution model
Untruncated approximation | `estimate_dist(obs_time_threshold = ...)` | Skip the right-truncation renormalisation when observation times are far beyond the largest observed delay | Distribution model
Observation aggregation | Automatic | Identical delay-censoring-truncation strata are aggregated to speed up fitting | Distribution model

See also: distribution model, worked example

# 3 Model configuration

## 3.1 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

See also: estimate_infections model definition, options examples

## 3.2 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)

See also: GP implementation details, options examples, prior choice guide

## 3.3 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

See also: workflow vignette, prior choice guide, fitting delay distributions

## 3.4 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.

See also: workflow vignette, prior choice guide

## 3.5 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.

# 4 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).

## 4.1 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

See also: workflow vignette

## 4.2 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

See also: workflow vignette

# 5 Supporting utilities

## 5.1 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

See also: workflow vignette

## 5.2 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

See also: epinow vignette, getting started

## 5.3 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.