# Compute seasonal onset and burden levels from seasonal time series observations. This function performs automated and early detection of seasonal epidemic onsets and estimates the burden levels from time series dataset stratified by season. The seasonal onset estimates growth rates for consecutive time intervals and calculates the sum of cases. The burden levels use the previous seasons to estimate the levels of the current season. ```r combined_seasonal_output( tsd, disease_threshold = 20, family = c("poisson", "quasipoisson"), family_quant = c("lnorm", "weibull", "exp"), season_start = 21, season_end = season_start - 1, only_current_season = TRUE, ... ) ``` ## Arguments - `tsd`: An object containing time series data with 'time' and 'observation.' - `disease_threshold`: An integer specifying the threshold for considering a disease outbreak. For seasonal onset 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. For burden levels it defines the per time-step disease threshold that has to be surpassed for the observation to be included in the level calculations. - `family`: A character string specifying the family for modeling seasonal onset. - `family_quant`: A character string specifying the family for modeling burden levels. - `season_start, season_end`: Integers giving the start and end weeks of the seasons to stratify the observations by. - `only_current_season`: Should the output only include results for the current season? - `...`: Arguments passed to `seasonal_burden_levels()`, `fit_percentiles()` and `seasonal_onset()` functions. ## Returns An object containing two lists: onset_output and burden_output: onset_output: 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? burden_output: A list containing: * 'season': The season that burden levels are calculated for. * 'high_conf_level': (only for intensity_level method) The conf_level chosen for the high level. * 'conf_levels': (only for peak_level method) The conf_levels chosen to fit the 'low', 'medium', 'high' levels. * 'values': A named vector with values for 'very low', 'low', 'medium', 'high' levels. * 'par': The fit parameters for the chosen family. * par_1: * For 'weibull': Shape parameter. * For 'lnorm': Mean of the log-transformed observations. * For 'exp': Rate parameter. * 'par_2': * For 'weibull': Scale parameter. * For 'lnorm': Standard deviation of the log-transformed observations. * For 'exp': Not applicable (set to NA). * 'obj_value': The value of the objective function - (negative log-likelihood), which represent the minimized objective function value from the optimisation. Smaller value equals better optimisation. * 'converged': Logical. TRUE if the optimisation converged. * 'family': The distribution family used for the optimization. * 'weibull': Uses the Weibull distribution for fitting. * 'lnorm': Uses the Log-normal distribution for fitting. * 'exp': Uses the Exponential distribution for fitting. * 'disease_threshold': The input disease threshold, which is also the very low level. ## Examples ```r # Generate random flu season generate_flu_season <- function(start = 1, end = 1000) { random_increasing_obs <- round(sort(runif(24, min = start, max = end))) random_decreasing_obs <- round(rev(random_increasing_obs)) # Generate peak numbers add_to_max <- c(50, 100, 200, 100) peak <- add_to_max + max(random_increasing_obs) # Combine into a single observations sequence observations <- c(random_increasing_obs, peak, random_decreasing_obs) return(observations) } season_1 <- generate_flu_season() season_2 <- generate_flu_season() start_date <- as.Date("2022-05-29") end_date <- as.Date("2024-05-20") weekly_dates <- seq.Date(from = start_date, to = end_date, by = "week") tsd_data <- tsd( observation = c(season_1, season_2), time = as.Date(weekly_dates), time_interval = "week" ) # Run the main function combined_data <- combined_seasonal_output(tsd_data) # Print seasonal onset results print(combined_data$onset_output) # Print burden level results print(combined_data$burden_output) ```

combined_seasonal_output function