---
title: Model Features Summary
description: "Quick reference to package capabilities"
author: Epinowcast Team
output: rmarkdown::html_document
bibliography: library.bib
csl: https://raw.githubusercontent.com/citation-style-language/styles/master/apa-numeric-superscript-brackets.csl
vignette: >
  %\VignetteIndexEntry{Model Features Summary}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# 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](model.html).
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](#timesteps) |
| **Multi-stratification** | Age groups, regions, pathogens | [Stratification](#stratification) |
| **Mixed delay models** | Parametric + non-parametric delays | [Delay modelling](#delay-modelling) |
| **Report date effects** | Day-of-week patterns, structural reporting | [Report date effects](#report-date-effects) |
| **Latent process models** | Growth rates, renewal processes | [Latent models](#latent-models) |
| **Hierarchical effects** | Random effects, random walks | [Hierarchical structure](#hierarchical) |
| **Missing data handling** | Missing reference dates | [Missing data](#missing-data) |
| **Retrospective Rt** | Rt estimation from finalised counts without delay modelling | [Rt estimation vignette](single-timeseries-rt-estimation.html) |
| **Custom priors** | Inspect and replace default priors | [Prior specification](#priors) |
| **Model comparison** | LOO-CV, posterior predictive checks | [Model evaluation](#model-evaluation) |
| **Inference methods** | NUTS, pathfinder, pathfinder-initialised NUTS | [Inference methods vignette](inference-methods.html) |
| **Data visualisation** | Inspect preprocessing and nowcast output | [Visualisation](#visualisation) |

# Different Timesteps and Timespans {#timesteps}

`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](epinowcast.html) |
| 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:**

- `enw_preprocess_data()`: Set timestep during preprocessing
- `enw_aggregate_cumulative()`: Convert between timesteps

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

# Stratified and Multi-Group Nowcasting {#stratification}

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](germany-age-stratified-nowcasting.html) |
| 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](germany-age-stratified-nowcasting.html) demonstrates multi-group nowcasting with age stratification and hierarchical effects.

# Delay Modelling Approaches {#delay-modelling}

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](distributions.html) for details on the range of supported distributions.

**Key functions:**

- `enw_reference()`: Specify delay model
- See `?enw_reference` for formula details

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

# Report Date Effects and Structural Reporting {#report-date-effects}

Model report date effects and known reporting structures.

| Approach | When to use | How to specify | Example |
|----------|-------------|----------------|---------|
| Non-parametric report effects | Day-of-week or other report date patterns | `enw_report(non_parametric = ~1 + (1 | day_of_week))` | Flexible report date effects |
| Structural reporting schedules | Known fixed reporting cycles (e.g., weekly) | `enw_report(structural = structural_data)` | Weekly reporting on specific days |
| Day-of-week structural | Weekly reporting pattern | `enw_dayofweek_structural_reporting(pobs, "Monday")` | Monday-only reporting |
| Custom structural patterns | Complex reporting schedules | `enw_structural_reporting_metadata()` with custom data | Flexible aggregation |

**Key functions:**

- `enw_report()`: Specify report date model
- `enw_dayofweek_structural_reporting()`: Helper for day-of-week patterns
- `enw_structural_reporting_metadata()`: Create custom structural reporting metadata
- `enw_rolling_sum()`: Aggregate observations over timesteps
- See `?enw_report` for details

**Where to see it:** See `inst/examples/germany_weekly_reporting_daily_process_model.R` for an example with weekly reporting and a daily process model.

# Latent Process Models {#latent-models}

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

| Model type | What it assumes | How to specify (formulas for `r` unless stated) | 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](single-timeseries-rt-estimation.html) |
| 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:**

- `enw_expectation()`: Specify latent process model and observation modifiers
- See `?enw_expectation` for details

**Where to see it:** The [Rt estimation vignette](single-timeseries-rt-estimation.html) demonstrates renewal process models with generation times.

# Hierarchical Structure {#hierarchical}

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:**

- `enw_formula()`: Unified formula interface
- `rw()`: Random walk helper
- See `?enw_formula` for syntax details

**Where to see it:** The [Germany case study](germany-age-stratified-nowcasting.html) uses random effects for age groups.
All model modules support the same formula interface.

# Prior Specification {#priors}

Each model module defines default normal priors which can be inspected and customised.
To set custom priors, pass a `data.frame` with columns `variable`, `mean`, and `sd` to the `priors` argument of `epinowcast()`.

| Task | How to do it | Details |
|------|--------------|---------|
| Inspect module priors | `enw_reference(data = pobs)$priors` | Each module returns its defaults |
| Replace specific priors | `enw_replace_priors(priors, custom)` | Merge custom values into defaults |
| Pass to model | `epinowcast(..., priors = custom_priors)` | Overrides matching defaults |

**Key functions:**

- `enw_replace_priors()`: Merge custom priors with defaults
- See `?epinowcast` for a worked example

# Missing Data Handling {#missing-data}

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:**

- `enw_missing()`: Model for missing reference dates
- `enw_extend_date()`: Extend time series with unobserved dates
- `enw_flag_observed_observations()`: Flag observations based on NAs
- `enw_obs()`: Use `observation_indicator` to control likelihood

**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:**

- NA handling example: See `?enw_flag_observed_observations` and `?enw_obs` for examples
- Other use cases: See function documentation for `enw_missing`, `enw_extend_date`

# Model Evaluation {#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](model.html) |
| LOO-CV | Model comparison | `enw_fit_opts(output_loglik = TRUE)` + `loo` package | See `?loo::loo` |
| Scoring rules | Probabilistic forecast evaluation | `scoringutils` package | [Germany hierarchical vignette](germany-age-stratified-nowcasting.html) |
| Convergence diagnostics | MCMC quality checks | Check `$fit$summary()` | [Stan help vignette](stan-help.html) |

**Key functions:**

- `enw_fit_opts()`: Control outputs
- `plot()`: Visualise results
- External: `loo`, `scoringutils` packages

**Where to see it:** The [Rt estimation vignette](single-timeseries-rt-estimation.html) shows model scoring and evaluation.

# Visualisation {#visualisation}

`plot()` methods are available for both preprocessed data and nowcast output.

| Object | Plot types | What it shows |
|--------|-----------|---------------|
| `enw_preprocess_data` | `"obs"`, `"delay_cumulative"`, `"delay_fraction"`, `"delay_quantiles"`, `"delay_counts"` | Reporting patterns and delay structure |
| `epinowcast` | `"nowcast"`, `"posterior_prediction"` | Nowcast estimates and posterior predictive checks |

**Key functions:**

- `plot()`: S3 methods for both object types
- `enw_plot_delay_cumulative()`, `enw_plot_delay_fraction()`, `enw_plot_delay_quantiles()`, `enw_plot_delay_counts()`: Individual plot functions for preprocessed data
- `enw_plot_nowcast_quantiles()`, `enw_plot_pp_quantiles()`: Individual plot functions for model output
- `enw_delay_categories()`, `enw_delay_quantiles()`: Helper functions for computing delay summaries

**Where to see it:** The [visualising preprocessed data vignette](preprocess-visualisation.html) demonstrates all preprocessing plot types.

# 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:**

- `enw_fit_opts()`: Specify computational options
- See `?enw_fit_opts` for details

**Where to see it:** The [inference methods vignette](inference-methods.html) compares NUTS, pathfinder, and pathfinder-initialised NUTS with runtime and posterior comparisons. See also the [Stan help vignette](stan-help.html) 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](epinowcast.html) 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](https://community.epinowcast.org/) or [GitHub discussions](https://github.com/epinowcast/epinowcast/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 |
| Delay-only models | Not supported | Currently requires count data alongside delay modelling |
| **Retrospective Rt estimation** | Supported | Use `max_delay = 1` or `enw_retrospective()` to skip delay modelling and estimate Rt from finalised counts. See the [Rt estimation vignette](single-timeseries-rt-estimation.html) |
| 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](https://community.epinowcast.org/) for ongoing discussions.

# Further Reading

- [Getting started vignette](epinowcast.html): Basic workflow
- [Model definition vignette](model.html): Mathematical details
- [Germany case study](germany-age-stratified-nowcasting.html): Age-stratified nowcasting
- [Rt estimation vignette](single-timeseries-rt-estimation.html): Renewal process models
- [Visualising preprocessed data](preprocess-visualisation.html): Explore delay structure before fitting
- [Distributions vignette](distributions.html): Parametric distributions
- Function documentation: `?function_name` for detailed API
- Package website: https://package.epinowcast.org