rt_pipeline: Real-time Pipeline

In epiforecasts/EpiNow: Estimate Realtime Case Counts and Time-varying Epidemiological Parameters

Description

Combine fitting a delay distribution, constructing a set of complete sampled linelists, nowcast cases by onset date, and estimate the time-varying effective reproduction number and rate of spread.

Usage

rt_pipeline(
  cases = NULL,
  linelist = NULL,
  delay_defs = NULL,
  incubation_defs = NULL,
  delay_cutoff_date = NULL,
  rt_samples = 5,
  rt_windows = 1:7,
  rate_window = 7,
  earliest_allowed_onset = NULL,
  merge_actual_onsets = TRUE,
  approx_delay = FALSE,
  approx_threshold = 10000,
  max_delay = 120,
  generation_times = NULL,
  rt_prior = NULL,
  nowcast_lag = 8,
  forecast_model = NULL,
  horizon = 0,
  report_forecast = FALSE,
  onset_modifier = NULL,
  min_forecast_cases = 200,
  target_folder = NULL,
  target_date = NULL,
  max_upscale = 5,
  dt_threads = 1,
  verbose = FALSE
)

Arguments

cases	A dataframe of cases (in date order) with the following variables: date and cases.
linelist	A dataframe of of cases (by row) containing the following variables: import_status (values "local" and "imported"), date_onset, date_confirm, report_delay.
delay_defs	A data.table that defines the delay distributions (model, parameters and maximum delay for each model). See get_delay_dist for an example of the structure.
incubation_defs	A data.table that defines the incubation distributions (model, parameters and maximum delay for each model). See get_delay_dist for an example of the structure.
delay_cutoff_date	Character string, in the form "2020-01-01". Cutoff date to use to estimate the delay distribution.
rt_samples	Numeric, the number of samples to take from the estimated R distribution for each time point.
rt_windows	Numeric vector, windows over which to estimate time-varying R. The best performing window will be selected per serial interval sample by default (based on which window best forecasts current cases).
rate_window	Numeric, the window to use to estimate the rate of spread.
earliest_allowed_onset	A character string in the form of a date ("2020-01-01") indiciating the earliest allowed onset.
merge_actual_onsets	Logical, defaults to TRUE. Should linelist onset dates be used where available?
approx_delay	Logical, defaults to FALSE. Should delay sampling be approximated using case counts. Not appropriate when case numbers are low. Useful for high cases counts as decouples run time and resource usage from case count.
approx_threshold	Numeric, defaults to 10,000. Threshold of cases below which explicit sampling of onsets always occurs.
max_delay	Numeric, maximum delay to allow. Defaults to 120 days
generation_times	A matrix with columns representing samples and rows representing the probability of the serial intervel being on that day. Defaults to EpiNow::covid_generation_times.
rt_prior	A list defining the reproduction number prior containing the mean (mean_prior) and standard deviation (std_prior)
nowcast_lag	Numeric, defaults to 4. The number of days by which to lag nowcasts. Helps reduce bias due to case upscaling.
forecast_model	An uninitialised bsts model passed to EpiSoon::forecast_rt to be used for forecasting future Rt values. An example of the required structure is: function(ss, y){bsts::AddSemilocalLinearTrend(ss, y = y)}.
horizon	Numeric, defaults to 0. The horizon over which to forecast Rts and cases.
report_forecast	Logical, defaults to FALSE. Should the forecast be reported.
onset_modifier	data.frame containing a date variable and a function modifier variable. This is used to modify estimated cases by onset date. modifier must be a function that returns a proportion when called (enables inclusion of uncertainty) and takes the following arguments: n (samples to return) and status ("local" or "import").
min_forecast_cases	Numeric, defaults to 200. The minimum number of cases required in the last 7 days of data in order for a forecast to be run. This prevents spurious forecasts based on highly uncertain Rt estimates.
target_folder	Character string indicating the folder into which to save results. Also used to extract previously generated results.
target_date	Character string, in the form "2020-01-01". Date to cast.
max_upscale	Numeric, maximum upscaling of cases allowed at each time point. Defaults to 100 times the observed cases.
dt_threads	Numeric, the number of data.table threads to use. Set internally to avoid issue when running in parallel. Defaults to 1 thread.
verbose	Logical, defaults to FALSE. Should internal nowcasting progress messages be returned.

Examples

## Not run: 
## Save everything to a temporary directory 
## Change this to inspect locally
target_dir <- tempdir()

## Construct example distributions
## reporting delay dist
delay_dist <- suppressWarnings(
               EpiNow::get_dist_def(rexp(25, 1/10), 
                                    samples = 5, bootstraps = 1))

## Uses example case vector from EpiSoon
cases <- data.table::setDT(EpiSoon::example_obs_cases)
cases <- cases[, `:=`(confirm = as.integer(cases), import_status = "local")][,
                  cases := NULL]

## Run basic nowcasting pipeline
rt_pipeline(cases = cases,
            delay_defs = delay_dist,
            target_date = max(cases$date),
            target_folder = target_dir)
            
            
## Run with forecasting and approximate delay sampling

## Requires additional packages:
library(EpiSoon)
library(forecastHybrid)

## Runs the estimation pipeline as before but this time with a 14 day Rt and case forecast
## Uses the {forecastHybrid} package to produce an unweighted
## ensemble using the last 3 weeks of data
rt_pipeline(cases = cases,
            delay_defs = delay_dist,
            target_date = max(cases$date),
            approx_delay = TRUE,
            target_folder = target_dir,
            horizon = 14, 
            report_forecast = TRUE
            nowcast_lag = 8,
            forecast_model = function(y, ...){EpiSoon::forecastHybrid_model(
            y = y[max(1, length(y) - 21):length(y)],
            model_params = list(models = "aefz", weights = "equal"),
            forecast_params = list(PI.combination = "mean"), ...)})


## End(Not run)

epiforecasts/EpiNow documentation built on Oct. 26, 2020, 2:38 p.m.