Skip to contents

Generic Method for Incidence Analysis

Source: R/incidence.R
incidence.Rd

Computes epidemiological incidence, defined as the number of new cases occurring at a specific time point, derived by exponentiating the log-incidence estimates from the fitted model: $$I_t = \exp(\log\text{-incidence}_t)$$

Usage

incidence(fitted_model, dow = NULL, ...)

# S3 method for class 'ps'
incidence(fitted_model, dow = NULL, ...)

# S3 method for class 'rw'
incidence(fitted_model, dow = NULL, ...)

# S3 method for class 'ps_single'
incidence(fitted_model, dow = NULL, ...)

# S3 method for class 'rw_single'
incidence(fitted_model, dow = NULL, ...)

Arguments

fitted_model

Fitted model object with class EpiStrainDynamics.fit

dow

Logical indicating whether to include day-of-week effects. If NULL or NA (default), uses the day-of-week setting from the fitted model. If TRUE, includes day-of-week effects (model must have been fitted with dow_effect = TRUE). If FALSE, excludes day-of-week effects.

...

Additional arguments passed to metrics calculation

Value

named list of class EpiStrainDynamics.metric containing a dataframe of the calculated metric outcome ($measure), the fit object ($fit), and the constructed model object ($constructed_model). The measure data frame contains the median of the epidemiological quantity (y), the 50% credible interval of the quantity (lb_50 & ub_50), the 95% credible interval (lb_95 & ub_95), the proportion greater than a defined threshold value (prop), the pathogen name (pathogen), and the time label (time).

Details

This metric quantifies the absolute number of new cases at each time point, where it is:

  • Always positive (since it's an exponentiated value)

  • Represents the expected case count at time t

  • Can be adjusted for day-of-week effects when modeled

  • Provides uncertainty quantification through posterior credible intervals

Day-of-week adjustment: When day-of-week effects are included in the model, the incidence is further adjusted as: $$I_t^{adj} = I_t \times \text{week\_effect} \times \text{dow\_simplex}[\text{DOW}(t)]$$

Where:

  • \(\text{week\_effect}\) is the number of distinct days modelled (7 for a full weekly cycle)

  • \(\text{dow\_simplex}\) gives the relative reporting weight for each day of the week, estimated from the data

  • \(\text{DOW}(t)\) maps time \(t\) to its day of the week

This accounts for systematic variations in case reporting (e.g. lower weekend reporting) that are not part of the underlying transmission trend.

This metric function can be run directly on the fitted model output.

See also

Other metrics: Rt(), growth_rate(), proportion()

Examples

if (FALSE) { # interactive()
mod <- construct_model(
  pathogen_structure = single(
    case_timeseries = sarscov2$cases,
    time = sarscov2$date
  ),
  method = random_walk()
)

fit <- fit_model(mod)

# Use model's dow setting (default)
inc <- incidence(fit)

# Explicitly exclude dow effects
inc_no_dow <- incidence(fit, dow = FALSE)

# Explicitly include dow effects (if model has them)
inc_with_dow <- incidence(fit, dow = TRUE)
}