rt_pipeline: Real-time Pipeline

Description Usage Arguments Examples

View source: R/rt_pipeline.R

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
## 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.