Skip to contents

Automated and Early Detection of Seasonal Epidemic Onset

Source: R/seasonal_onset.R
seasonal_onset.Rd

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
)

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?

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?

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
)
#> # A tibble: 4 × 13
#>   reference_time observation season      growth_rate lower_growth_rate
#>   <date>               <dbl> <chr>             <dbl>             <dbl>
#> 1 2023-01-03             150 not_defined       0.204            0.0785
#> 2 2023-01-04             180 not_defined       0.201            0.0874
#> 3 2023-01-05             220 not_defined       0.192            0.0891
#> 4 2023-01-06             270 not_defined       0.203            0.109 
#> # ℹ 8 more variables: upper_growth_rate <dbl>, growth_warning <lgl>,
#> #   sum_of_cases <dbl>, sum_of_cases_warning <lgl>, seasonal_onset_alarm <lgl>,
#> #   skipped_window <lgl>, converged <lgl>, seasonal_onset <lgl>