ViroReportR: Respiratory Viral Infection Forecast Reporting

Description

Tools for reporting and forecasting viral respiratory infections, using case surveillance data. Report generation tools for short-term forecasts, and validation metrics for an arbitrary number of customizable respiratory viruses. Estimation of the effective reproduction number is based on the 'EpiEstim' framework described in work by 'Cori' and colleagues. (2013) doi:10.1093/aje/kwt133.

Author(s)

Maintainer: Mike Irvine mike.irvine@bccdc.ca [copyright holder]

Authors:

• Caesar Wong

• Nirupama Tamvada

• Rebeca Falcao

• Nelson Tang

See Also

Useful links:

• https://github.com/BCCDC-PHSA/ViroReportR

• Report bugs at https://github.com/BCCDC-PHSA/ViroReportR/issues

Check Matching Names in Named Vectors

Description

Internal utility function to verify that all input named vectors share the same names.

Usage

check_match_names(...)

Arguments

Value

Throws an error if name mismatches are found; otherwise, returns nothing.

Clean and validate case count data for EpiEstim

Description

This function prepares case count data for use with EpiEstim by performing a series of validation and cleaning steps:

Usage

clean_sample_data(data, start_date)

Arguments

Details

1. Ensures that the input data frame has the required columns: "date" and "confirm".

2. Confirms that the specified start_date exists in the data and filters the data to include only records on or after that date.

3. Removes leading days before the first non-zero confirmed case.

4. Verifies that the resulting dataset contains at least 14 valid days (as required for estimation).

This function is primarily intended as a preprocessing step for EpiEstim modeling. It combines validation checks for input structure and time coverage with minimal data cleaning logic to ensure robust downstream estimation.

Value

A cleaned data frame filtered from start_date, starting at the first date with non-zero confirmed cases, and containing at least 14 days of data.

summarise a data frame d by groups along a variable

Description

summarise a data frame d by groups along a variable

Usage

create_quantiles(d, ..., variable = NULL)

Arguments

Value

Data frame containing sample quantiles at probabilities 0.05, 0.25, 0.50, 0.75 and 0.95

Print out text output for ViroReportR report detailing current number of case visits, last value of Rt and corresponding intervals

Description

Print out text output for ViroReportR report detailing current number of case visits, last value of Rt and corresponding intervals

Usage

current_forecast_text(time_period_result, ...)

Arguments

Value

current forecast metrics

fit_epiestim_model - Function to estimate the reproduction number of an epidemic

Description

A wrapper function for estimate_R from the EpiEstim library to estimate the reproduction number of epidemics to support short-term forecasts

Usage

fit_epiestim_model(
  data,
  window_size = 7L,
  type = NULL,
  mean_si = NULL,
  std_si = NULL,
  recon_opt = "match",
  method = "parametric_si",
  mean_prior = NULL,
  std_prior = NULL
)

Arguments

Details

fit_epiestim_model currently supports the following epidemics: Influenza, RSV and COVID-19. The default serial intervals for the estimation of R were retrieved from Cowling et al., 2011, Vink et al., 2014 and Madewell et al., 2023 for Influenza A, Influenza B, RSV and COVID (BA.5 Omicron variant) respectively

Value

Object of class estimate_R (see EpiEstim help page)

Extract current forecast metrics: forecast prediction, percentile interval and Rt value

Description

Extract current forecast metrics: forecast prediction, percentile interval and Rt value

Usage

forecast_metrics(time_period_result, iter = 10)

Arguments

Value

dataframe of current forecast metrics

Forecast daily epidemic cases using EpiEstim

Description

This function prepares epidemic data, estimates the reproduction number (R_t) using fit_epiestim_model, and produces short-term forecasts of daily confirmed cases with project_epiestim_model.

It removes early periods with no cases, checks data validity, optionally smooths the epidemic curve, and then generates forward projections of cases for a specified number of days.

Usage

generate_forecast(
  data,
  start_date,
  window_size = 7,
  n_days = 7,
  type = NULL,
  smooth_data = FALSE,
  smoothing_cutoff = 10,
  ...
)

Arguments

Details

• Data prior to the first non-zero confirm value is excluded.

• Input is checked for validity (sufficient days, proper format).

• If smoothing is enabled, case counts are adjusted before fitting.

• Forecasts are generated from the fitted EpiEstim model and returned with quantiles (2.5%, 25%, 50%, 75%, 97.5%), minimum, and maximum.

Value

A data frame of forecasted daily incidence with columns:

• date: date of forecast

• p50, p25, p75, p025, p975: forecast quantiles

• min_sim, max_sim: forecast range

See Also

fit_epiestim_model for reproduction number estimation, project_epiestim_model for forward simulations.

Examples

# Create sample test rsv data
disease_type <- "rsv"
test_data <- simulate_data()
formatted_data <- get_aggregated_data(
  test_data,
  number_column = disease_type,
  date_column = "date",
  start_date = "2024-04-01",
  end_date = "2024-05-01"
)

# Run a 7 day forecast with smoothing
res_smooth <- generate_forecast(
  data = formatted_data,
  start_date = "2024-04-01",
  n_days = 7,
  type = "rsv",
  smooth_data = FALSE
)

Generate Viral Respiratory Forecast Report

Description

Generates a full-season forecast report for viral respiratory diseases as an HTML document.

Usage

generate_forecast_report(
  input_data_dir = NULL,
  output_dir = NULL,
  n_days = 7,
  validate_window_size = 7,
  smooth = FALSE,
  disease_season = NULL
)

Arguments

Value

Invisibly returns the path to the rendered HTML report.

Examples

data <- simulate_data(start_date = "2024-01-07", #starting Sunday
)
diseases <- c("flu_a", "rsv", "sars_cov2")
data$date <- lubridate::ymd(data$date)
vri_data_list <- purrr::set_names( purrr::map2( rep(list(data), length(diseases)),
                                  diseases,
                                  ~ get_aggregated_data(.x, "date", .y)
                                 ),
                            diseases
)
# Save the simulated data
df <- purrr::imap_dfr(
vri_data_list,
\(df, disease) dplyr::mutate(df, disease_type = disease)
)
tmp_dir <- tempdir() # temporary directory for example for saving data
data_path <- file.path(tmp_dir, "simulated_data.csv")
write.csv(df, data_path, row.names = FALSE)

output_path <- tempdir() # output directory for report (temporary as example)
generate_forecast_report(input_data_dir = data_path,
                         output_dir = output_path,
                         n_days = 7,
                         validate_window_size = 7,
                         smooth = FALSE)

Validate forecast performance over multiple time windows

Description

This function performs rolling validation of short-term forecasts generated by EpiEstim or similar models. It divides the input time series into overlapping validation windows and repeatedly runs forecasts to assess model performance across different time segments.

Usage

generate_validation(
  data,
  start_date,
  validate_window_size = 7,
  window_size = 7,
  n_days = 7,
  type = NULL,
  smooth_data = FALSE,
  smoothing_cutoff = 10,
  ...
)

Arguments

Details

The validation procedure ensures that forecasts are evaluated under realistic temporal conditions. Starting from the earliest date, the function repeatedly:

1. Takes a growing subset of data up to the current validation endpoint.

2. Runs the forecast using generate_forecast().

3. Moves the validation window forward by validate_window_size days.

This results in a set of forecasts that can be compared to observed data to evaluate predictive performance across time.

Value

A list of forecast results, each element corresponding to one validation window. Each element contains the output returned by generate_forecast() for that particular window.

See Also

clean_sample_data(), generate_forecast()

Examples

data <- simulate_data()
formatted_data <- get_aggregated_data(data,"date", "flu_a", "2024-10-16", "2024-12-31")
start_date <- as.Date("2024-10-16")
validation_results <- generate_validation(formatted_data, start_date, type="flu_a")

Compute Forecast Validation Metrics (SMAPE & MASE)

Description

This function evaluates forecast accuracy across multiple validation runs by computing two key performance metrics:

Usage

generate_validation_metric(data, validation_res)

Arguments

Details

• Symmetric Mean Absolute Percentage Error (SMAPE): Measures relative forecast accuracy while remaining robust to zero values in the actual data.

• Mean Absolute Scaled Error (MASE): Scales forecast errors relative to the in-sample one-step naïve forecast, allowing comparison across series with different scales.

For each forecast result, the function also reports the corresponding training and forecast periods. Computation stops once the forecast period reaches the maximum date in the model data.

• SMAPE is defined as:

  SMAPE = mean( |F - A| / ((|A| + |F|) / 2) )

  where \(A\) are actual values and \(F\) are forecasts. It avoids division by zero and is suitable for count data with zeros.

• MASE compares the mean absolute forecast error against the mean absolute difference of successive actual:

  MASE = mean(|A - F|) / mean(|diff(A)|)

The function automatically excludes forecasts extending beyond the latest date in the observed model data.

Value

A tibble (data frame) with one row per forecast result and the following columns:

• train_period: Date range of the training period used for the forecast.

• forecast_period: Date range of the forecasted period.

• smape: Symmetric Mean Absolute Percentage Error between forecasted and actual values, rounded to two decimals.

• mase: Mean Absolute Scaled Error, rounded to two decimals.

See Also

generate_validation(), generate_forecast()

Examples

data <- simulate_data()
formatted_data <- get_aggregated_data(data,"date", "flu_a", "2024-10-16", "2024-12-31")
start_date <- ("2024-10-16")
validation_results <- generate_validation(formatted_data, start_date, type ="flu_a")
generate_validation_metric(formatted_data, validation_results)

Extract Aggregated Weekly Generic Data

Description

get_aggregated_data() performs data transformation in the following steps:

1. Group the weekly or daily data by date.

2. Aggregate the number of confirmed cases by either day or week.

3. Select only the date and confirmed cases column.

4. Filter the data by given start and end date

The input dataframe generic_data must have the following columns:

• ⁠<date name>⁠: date column (e.g. as.Date('2022-01-01')).

• ⁠<cases count name>⁠: Confirmed Cases Count (e.g. 1, 2, ...).

Note that these columns can be defined in a generic name, and inputted as the other two function parameters for data transformation (date_column, number_column)

Assume the date column is the start of the epiweek.

Usage

get_aggregated_data(
  generic_data,
  date_column,
  number_column,
  start_date = NULL,
  end_date = NULL,
  unit = "day"
)

Arguments

Value

aggregated weekly data of the generic confirmed cases data (filtered by date if any)

date

Either day or week date

confirm

number of confirmed cases

Examples

sim_data <- simulate_data()
aggregated_data <- get_aggregated_data(
  sim_data,
  "date", "flu_a", "2024-10-16", "2024-12-31"
)

Compare Reproduction Number Estimates from Multiple EpiEstim Outputs

Description

This function is deprecated and may be removed in a future release.

This function creates a ggplot comparing estimated reproduction numbers (R) over time from multiple EpiEstim outputs. Each input should be a named object produced by EpiEstim containing an estimate_R$R data frame.

Usage

plot_R_fit_comparison(...)

Arguments

Value

A ggplot2 object showing median R estimates with 50% and 95% credible intervals, colored by input source (i.e., name).

See Also

generate_forecast(), EpiEstim::estimate_R()

Compare Forecast Outputs

Description

This function is deprecated and may be removed in a future release.

This function visualizes and compares multiple forecast outputs generated by generate_forecast(). It plots median predicted incidences with 80% and 90% predictive intervals.

Usage

plot_forecast_comparison(...)

Arguments

Value

A ggplot2 object showing forecasted median incidences over time with shaded prediction intervals, colored by input source (i.e., model name).

See Also

generate_forecast(), ggplot2::ggplot()

Plot Mean Rt with time index (dates)

Description

Plot Mean Rt with time index (dates)

Usage

plot_rt(forecast_results)

Arguments

Value

Mean Rt with time index plot

Examples

# Create sample test rsv data
disease_type <- "rsv"
test_data <- simulate_data()
formatted_data <- get_aggregated_data(
  test_data,
  number_column = disease_type,
  date_column = "date",
  start_date = "2024-04-01",
  end_date = "2024-05-01"
)

# Run a 7 day forecast with smoothing
forecast_results <- generate_forecast(
  data = formatted_data,
  start_date = "2024-04-01",
  n_days = 7,
  type = "rsv",
  smooth_data = FALSE
)
plot_rt(forecast_results)

Plot a ribbon plot with each time horizon predictions against true values for validation

Description

Plot a ribbon plot with each time horizon predictions against true values for validation

Usage

plot_validation(data, validation_res, pred_plot = "ribbon")

Arguments

Value

error_bar validation plot or ribbon validation plot for a specific prediction horizon

Examples

data <- simulate_data()
formatted_data <- get_aggregated_data(data,"date", "flu_a", "2024-10-16", "2024-12-31")
start_date <- ("2024-10-16")
validation_results <- generate_validation(formatted_data, start_date, type ="flu_a")
plot_validation(formatted_data, validation_results)

Extract daily forecast samples

Description

Function to produce short-term daily projections from objects of class estimate_R

Usage

project_epiestim_model(data, model_fit, n_days = 7, n_sim = 1000)

Arguments

Value

Data-frame of daily forecast samples from all simulations

date

date

incidence

projected number of daily confirmed cases

sim

simulation run number

Simulate Daily Virus Incidence Data

Description

Generates simulated daily incidence data for specified respiratory viruses over a defined number of days. Each virus is modeled using a Gaussian-like curve, parameterized by peak day, amplitude, and scale.

Usage

simulate_data(
  days = 365,
  peaks = c(flu_a = 90, rsv = 110, sars_cov2 = 160),
  amplitudes = c(flu_a = 50, rsv = 40, sars_cov2 = 20),
  scales = c(flu_a = -0.004, rsv = -0.005, sars_cov2 = -0.001),
  time_offset = 0,
  noise_sd = 5,
  start_date = "2024-01-07"
)

Arguments

Value

A data frame with daily simulated incidence counts for each virus, including a date column.

Examples

simulate_data()
simulate_data(days = 100, peaks = c(flu_a = 30), amplitudes = c(flu_a = 60),
scales = c(flu_a = -0.01), noise_sd = c(flu_a = 5))