Skip to contents

Model Features Summary

Epinowcast Team

Source: vignettes/features.Rmd
features.Rmd

Overview

This vignette provides a high-level summary of what epinowcast can do. Rather than duplicating detailed documentation, we signpost to examples and documentation for each capability.

For detailed model specification, see the model definition vignette. For function-specific details, see ?function_name.

Core Capabilities

Capability What it enables Where to learn more
Flexible timesteps Daily, weekly, or custom aggregation Different timesteps
Multi-stratification Age groups, regions, pathogens Stratification
Mixed delay models Parametric + non-parametric delays Delay modelling
Latent process models Growth rates, renewal processes Latent models
Hierarchical effects Random effects, random walks Hierarchical structure
Missing data handling Missing reference dates Missing data
Model comparison LOO-CV, posterior predictive checks Model evaluation

Different Timesteps and Timespans

epinowcast supports flexible temporal aggregation to match your data structure and computational constraints.

Timestep Use case How to specify Example
Daily High resolution surveillance timestep = "day" (default) Getting started vignette
Weekly Reduced computational cost timestep = "week" enw_preprocess_data(..., timestep = "week")
Custom Any integer multiple of days timestep = 7 enw_preprocess_data(..., timestep = 7)

Key functions:

Where to see it: The getting started vignette uses daily data. For weekly or custom timesteps, simply change the timestep argument in enw_preprocess_data().

Stratified and Multi-Group Nowcasting

Nowcast across multiple groups simultaneously with hierarchical sharing of information.

Stratification type Use case How to specify Example
Age groups Age-stratified surveillance by = c("age_group") Germany age-stratified vignette
Geographic regions Regional nowcasts by = c("region") Set by in enw_preprocess_data()
Multiple factors E.g., age × region by = c("age_group", "region") Combine factors in by argument
Independent groups No sharing between groups Use .group in formulas Default behaviour
Hierarchical sharing Partial pooling Random effects in formulas ~1 + (1 | .group)

Key functions:

  • enw_preprocess_data(): Specify grouping with by argument
  • Formula interface: Control sharing via random effects

Where to see it: The Germany age-stratified case study demonstrates multi-group nowcasting with age stratification and hierarchical effects.

Delay Modelling Approaches

Model reporting delays using parametric distributions, non-parametric hazards, or combinations.

Approach When to use How to specify Example
Parametric only Sparse data (provides regularisation), faster fitting enw_reference(parametric = ~1, distribution = "lognormal") Default in vignettes
Non-parametric only Multimodal or highly complex delay patterns enw_reference(parametric = ~0, non_parametric = ~1 + (1 | delay)) Flexible hazard model
Mixed model Parametric baseline + adjustments for complex patterns enw_reference(parametric = ~1, non_parametric = ~0 + (1 | delay_cat)) Best of both
Time-varying delays Changing reporting over time Include time effects in formulas parametric = ~1 + week
Group-specific delays Different delays by strata Random effects by group parametric = ~1 + (1 | .group)

Available distributions: See the distributions vignette for details on the range of supported distributions.

Key functions:

Where to see it: All vignettes use delay models. For non-parametric approaches and mixed models, see ?enw_reference examples.

Latent Process Models

Specify the generative model for the expected latent process (e.g., infections, hospitalisations).

Model type What it assumes How to specify (r argument) Example
Daily random effects Flexible day-to-day changes ~0 + (1 | day:.group) (default) Most flexible
Weekly random walk Smooth week-to-week trends ~1 + rw(week, by = .group) Smoother estimates
Growth rate Exponential growth/decline generation_time = 1 (default) Simple trend
Renewal process Epidemic dynamics generation_time = c(0.2, 0.5, 0.3) Rt estimation vignette
Fixed effects Covariates (e.g., interventions) ~1 + intervention + ... Include predictors
Observation modifiers Ascertainment variation (e.g., day of week) observation = ~1 + day_of_week Adjust for reporting patterns

Key functions:

Where to see it: The Rt estimation vignette demonstrates renewal process models with generation times.

Hierarchical Structure

Build hierarchical models using the formula interface.

Feature What it does Syntax Use case
Random intercepts Group-level variation ~1 + (1 | group) Partial pooling between groups
Random slopes Group-specific effects ~x + (x | group) Effect varies by group
Random walks Temporal smoothing ~rw(time) Smooth trends over time
Grouped random walks Group-specific trends ~rw(time, by = group) Different trends per group
Sparse design Memory efficient sparse = TRUE in enw_formula() Large sparse matrices

Key functions:

Where to see it: The Germany case study uses random effects for age groups. All model modules support the same formula interface.

Missing Data Handling

Handle two types of missing data: missing reference dates and missing observations.

Type What it handles Use cases How to use
Missing reference dates Reports with known report date but unknown reference date Model partial reporting enw_missing(formula = ~1)
Missing observations Control which observations are used in the likelihood Forecasting, excluding outliers, handling NAs, testing parameter recovery Set .observed = FALSE and use observation_indicator in enw_obs()

Common missing observation workflows:

Use case How to implement
Forecasting enw_extend_date() to add future dates marked as unobserved
Exclude outliers Manually set .observed = FALSE for outlier observations
Handle NAs enw_flag_observed_observations() marks NA values as unobserved
Test parameter recovery Set .observed = FALSE for subset of data, check if model recovers parameters

Key functions:

Notes:

  • The missing reference model assumes consistent reporting delay for observations with and without known reference dates
  • Any observations marked with .observed = FALSE can be excluded from the likelihood whilst still generating posterior predictions

Where to see it:

Model Evaluation

Assess model fit and compare models.

Method What it provides How to use Where to learn
Posterior predictive checks Visual fit assessment enw_fit_opts(pp = TRUE) Model vignette
LOO-CV Model comparison enw_fit_opts(output_loglik = TRUE) + loo package See ?loo::loo
Scoring rules Probabilistic forecast evaluation scoringutils package Rt vignette
Convergence diagnostics MCMC quality checks Check $fit$summary() Stan help vignette

Key functions:

Where to see it: The Rt estimation vignette shows model scoring and evaluation.

Computational Options

Control computational efficiency and parallelisation.

Feature What it does How to specify When to use
Within-chain threading Parallel likelihood calculation across strata threads_per_chain = 4 Many strata, large datasets, complex models
Parallel chains Multiple chains simultaneously parallel_chains = 4 Multiple cores available
Sparse design matrices Memory reduction sparse_design = TRUE Very sparse designs
Likelihood aggregation Parallelisation level likelihood_aggregation = "snapshots" Default usually best
Pathfinder Fast approximate inference sampler = enw_pathfinder Exploration/debugging
Pathfinder initialisation Use pathfinder to initialise MCMC init_method = "pathfinder" in enw_sample Improve MCMC convergence

Key functions:

Where to see it: See Stan help vignette for guidance on computational settings.

Data Handling

Prepare and process data for nowcasting.

Task Functions Purpose
Convert from line list enw_linelist_to_incidence() Individual → aggregate data
Complete date sequences enw_complete_dates() Fill missing dates
Filter by dates enw_filter_report_dates(), enw_filter_reference_dates() Subset data
Add metadata enw_add_metaobs_features() Day of week, holidays, etc.
Change timesteps enw_aggregate_cumulative() Daily → weekly, etc.
Main preprocessing enw_preprocess_data() All-in-one wrapper

Where to see it: The getting started vignette demonstrates the full data preprocessing workflow.

Current Limitations

The following features are not currently supported but may be of interest. If you need any of these capabilities, please reach out via our community forum or GitHub discussions.

Feature Status Notes
Non-count data Not supported Currently limited to count data with Poisson/negative binomial likelihoods
Negative updates Not supported Cannot handle reporting corrections that reduce previously reported counts
Structured reporting schedules In development PR exists for aggregated reporting with known schedules
Delay-only or count-only models Not supported Currently requires joint modelling of delay and counts
Susceptibility depletion Not supported Renewal process assumes constant susceptibility
Uncertain generation time Not supported Generation time distribution treated as fixed and known
Forecasting examples Missing Functionality exists but lacks worked examples in vignettes

Get involved: We welcome contributions and discussions about extending the package to support these features. See our community forum for ongoing discussions.

Further Reading