aedseo (version 0.3.0)

seasonal_onset: Automated and Early Detection of Seasonal Epidemic Onset

Description

This function performs automated and early detection of seasonal epidemic onsets on a time series dataset. It estimates growth rates for consecutive time intervals and calculates the sum of cases (sum_of_cases).

Usage

seasonal_onset(
  tsd,
  k = 5,
  level = 0.95,
  disease_threshold = NA_integer_,
  family = c("poisson", "quasipoisson"),
  na_fraction_allowed = 0.4,
  season_start = NULL,
  season_end = season_start - 1,
  only_current_season = NULL
)

Value

A seasonal_onset object containing:

• 'reference_time': The time point for which the growth rate is estimated.

• 'observation': The observation in the reference time point.

• 'season': The stratification of observables in corresponding seasons.

• 'growth_rate': The estimated growth rate.

• 'lower_growth_rate': The lower bound of the growth rate's confidence interval.

• 'upper_growth_rate': The upper bound of the growth rate's confidence interval.

• 'growth_warning': Logical. Is the growth rate significantly higher than zero?

• 'sum_of_cases': The sum of cases within the time window.

• 'sum_of_cases_warning': Logical. Does the Sum of Cases exceed the disease threshold?

• 'seasonal_onset_alarm': Logical. Is there a seasonal onset alarm?

• 'skipped_window': Logical. Was the window skipped due to missing?

• 'converged': Logical. Was the IWLS judged to have converged? - 'seasonal_onset': Logical. The first detected seasonal onset in the season?

Arguments

tsd

An object containing time series data with 'time' and 'observation.'

k

An integer specifying the window size for modeling growth rates for the onset.

level

The confidence level for onset parameter estimates, a numeric value between 0 and 1.

disease_threshold

An integer specifying the threshold for considering a disease outbreak. It defines the per time-step disease threshold that has to be surpassed to possibly trigger a seasonal onset alarm. If the total number of cases in a window of size k exceeds disease_threshold * k, a seasonal onset alarm can be triggered.

family

A character string specifying the family for modeling

na_fraction_allowed

Numeric value between 0 and 1 specifying the fraction of observables in the window of size k that are allowed to be NA or zero, i.e. without cases, in onset calculations.

season_start, season_end

Integers giving the start and end weeks of the seasons to stratify the observations by. If set to NULL, it means no stratification by season.

only_current_season

Should the output only include results for the current season?

Examples

# Create a tibble object from sample data
tsd_data <- tsd(
  observation = c(100, 120, 150, 180, 220, 270),
  time = as.Date(c(
    "2023-01-01",
    "2023-01-02",
    "2023-01-03",
    "2023-01-04",
    "2023-01-05",
    "2023-01-06"
  )),
  time_interval = "day"
)

# Estimate seasonal onset with a 3-day window and a Poisson family model
seasonal_onset(
  tsd = tsd_data,
  k = 3,
  level = 0.95,
  disease_threshold = 20,
  family = "poisson",
  na_fraction_allowed = 0.4,
  season_start = NULL,
  season_end = NULL,
  only_current_season = NULL
)