Real-time Rt Estimation, Forecasting and Reporting

This function wraps the functionality of estimate_infections() in order to estimate Rt and cases by date of infection and forecast these infections into the future. In addition to the functionality of estimate_infections() it produces additional summary output useful for reporting results and interpreting them as well as error catching and reporting, making it particularly useful for production use e.g. running at set intervals on a dedicated server.

Usage

epinow(
  data,
  generation_time = gt_opts(),
  delays = delay_opts(),
  truncation = trunc_opts(),
  rt = rt_opts(),
  backcalc = backcalc_opts(),
  gp = gp_opts(),
  obs = obs_opts(),
  forecast = forecast_opts(),
  stan = stan_opts(),
  horizon,
  CrIs = c(0.2, 0.5, 0.9),
  filter_leading_zeros = TRUE,
  zero_threshold = Inf,
  return_output = is.null(target_folder),
  output = c("samples", "plots", "latest", "fit", "timing"),
  plot_args = list(),
  target_folder = NULL,
  target_date,
  logs = tempdir(),
  id = "epinow",
  verbose = interactive(),
  reported_cases
)

Arguments

data

A <data.frame> of confirmed cases (confirm) by date (date). confirm must be numeric and date must be in date format. Optionally this can also have a logical accumulate column which indicates whether data should be added to the next data point. This is useful when modelling e.g. weekly incidence data. See also the fill_missing() function which helps add the accumulate column with the desired properties when dealing with non-daily data. If any accumulation is done this happens after truncation as specified by the truncation argument.

generation_time

A call to gt_opts() (or its alias generation_time_opts()) defining the generation time distribution used. For backwards compatibility a list of summary parameters can also be passed.

delays

A call to delay_opts() defining delay distributions and options. See the documentation of delay_opts() and the examples below for details.

truncation

A call to trunc_opts() defining the truncation of the observed data. Defaults to trunc_opts(), i.e. no truncation. See the estimate_truncation() help file for an approach to estimating this from data where the dist list element returned by estimate_truncation() is used as the truncation argument here, thereby propagating the uncertainty in the estimate.

rt

A list of options as generated by rt_opts() defining Rt estimation. Defaults to rt_opts(). To generate new infections using the non-mechanistic model instead of the renewal equation model, use rt = NULL. The non-mechanistic model internally uses the setting rt = rt_opts(use_rt = FALSE, future = "project", gp_on = "R0").

backcalc

A list of options as generated by backcalc_opts() to define the back calculation. Defaults to backcalc_opts().

gp

A list of options as generated by gp_opts() to define the Gaussian process. Defaults to gp_opts(). Set to NULL to disable the Gaussian process.

obs

A list of options as generated by obs_opts() defining the observation model. Defaults to obs_opts().

forecast

A list of options as generated by forecast_opts() defining the forecast opitions. Defaults to forecast_opts(). If NULL then no forecasting will be one.

stan

A list of stan options as generated by stan_opts(). Defaults to stan_opts(). Can be used to override data, init, and verbose settings if desired.

horizon

Deprecated; use forecast instead to specify the predictive horizon

CrIs

Numeric vector of credible intervals to calculate.

filter_leading_zeros

Logical, defaults to TRUE. Should zeros at the start of the time series be filtered out.

zero_threshold

Numeric defaults to Inf. Indicates if detected zero cases are meaningful by using a threshold number of cases based on the 7-day average. If the average is above this threshold then the zero is replaced using fill.

return_output

Logical, defaults to FALSE. Should output be returned, this automatically updates to TRUE if no directory for saving is specified.

output

A character vector of optional output to return. Supported options are samples ("samples"), plots ("plots"), the run time ("timing"), copying the dated folder into a latest folder (if target_folder is not null, set using "latest"), and the stan fit ("fit"). The default is to return all options.

plot_args

A list of optional arguments passed to plot.epinow().

target_folder

Character string specifying where to save results (will create if not present).

target_date

Date, defaults to maximum found in the data if not specified.

logs

Character path indicating the target folder in which to store log information. Defaults to the temporary directory if not specified. Default logging can be disabled if logs is set to NULL. If specifying a custom logging setup then the code for setup_default_logging() and the setup_logging() function are a sensible place to start.

id

A character string used to assign logging information on error. Used by regional_epinow() to assign errors to regions. Alter the default to run with error catching.

verbose

Logical, defaults to TRUE when used interactively and otherwise FALSE. Should verbose debug progress messages be printed. Corresponds to the "DEBUG" level from futile.logger. See setup_logging for more detailed logging options.

reported_cases

Deprecated; use data instead.

Value

A list of output from estimate_infections with additional elements summarising results and reporting errors if they have occurred.

See also

estimate_infections() forecast_infections() regional_epinow()

Examples

# \donttest{
# set number of cores to use
old_opts <- options()
options(mc.cores = ifelse(interactive(), 4, 1))

# set an example generation time. In practice this should use an estimate
# from the literature or be estimated from data
generation_time <- Gamma(
  shape = Normal(1.3, 0.3),
  rate = Normal(0.37, 0.09),
  max = 14
)
# set an example incubation period. In practice this should use an estimate
# from the literature or be estimated from data
incubation_period <- LogNormal(
   meanlog = Normal(1.6, 0.06),
   sdlog = Normal(0.4, 0.07),
   max = 14
)
# set an example reporting delay. In practice this should use an estimate
# from the literature or be estimated from data
reporting_delay <- LogNormal(mean = 2, sd = 1, max = 10)

# example case data
reported_cases <- example_confirmed[1:40]

# estimate Rt and nowcast/forecast cases by date of infection
out <- epinow(
  data = reported_cases,
  generation_time = gt_opts(generation_time),
  rt = rt_opts(prior = LogNormal(mean = 2, sd = 0.1)),
  delays = delay_opts(incubation_period + reporting_delay)
)
#> Logging threshold set at INFO for the name logger
#> Writing EpiNow2 logs to the console and:
#> /tmp/RtmplSYXcX/regional-epinow/2020-04-01.log.
#> Logging threshold set at INFO for the name logger
#> Writing EpiNow2.epinow logs to the console and:
#> /tmp/RtmplSYXcX/epinow/2020-04-01.log.
#> WARN [2024-12-20 21:37:42] epinow: The `filter_leading_zeros` argument of `estimate_infections()` is deprecated as of EpiNow2 1.7.0. - 
#> WARN [2024-12-20 21:37:42] epinow: The `zero_threshold` argument of `estimate_infections()` is deprecated as of EpiNow2 1.7.0. - 
# summary of the latest estimates
summary(out)
#>                             measure                 estimate
#>                              <char>                   <char>
#> 1:           New infections per day      3673 (1935 -- 7213)
#> 2: Expected change in daily reports        Likely decreasing
#> 3:       Effective reproduction no.         0.81 (0.62 -- 1)
#> 4:                   Rate of growth -0.063 (-0.13 -- 0.0091)
#> 5:     Doubling/halving time (days)         -11 (76 -- -5.3)
# plot estimates
plot(out)


# summary of R estimates
summary(out, type = "parameters", params = "R")
#>           date variable  strat                           type    median
#>         <Date>   <char> <char>                         <char>     <num>
#>  1: 2020-02-22        R   <NA>                       estimate 2.0964883
#>  2: 2020-02-23        R   <NA>                       estimate 2.0776956
#>  3: 2020-02-24        R   <NA>                       estimate 2.0570210
#>  4: 2020-02-25        R   <NA>                       estimate 2.0319952
#>  5: 2020-02-26        R   <NA>                       estimate 2.0081830
#>  6: 2020-02-27        R   <NA>                       estimate 1.9800889
#>  7: 2020-02-28        R   <NA>                       estimate 1.9488347
#>  8: 2020-02-29        R   <NA>                       estimate 1.9145541
#>  9: 2020-03-01        R   <NA>                       estimate 1.8780965
#> 10: 2020-03-02        R   <NA>                       estimate 1.8382382
#> 11: 2020-03-03        R   <NA>                       estimate 1.7972837
#> 12: 2020-03-04        R   <NA>                       estimate 1.7552119
#> 13: 2020-03-05        R   <NA>                       estimate 1.7109359
#> 14: 2020-03-06        R   <NA>                       estimate 1.6643093
#> 15: 2020-03-07        R   <NA>                       estimate 1.6182834
#> 16: 2020-03-08        R   <NA>                       estimate 1.5729894
#> 17: 2020-03-09        R   <NA>                       estimate 1.5261054
#> 18: 2020-03-10        R   <NA>                       estimate 1.4803868
#> 19: 2020-03-11        R   <NA>                       estimate 1.4345270
#> 20: 2020-03-12        R   <NA>                       estimate 1.3877141
#> 21: 2020-03-13        R   <NA>                       estimate 1.3432033
#> 22: 2020-03-14        R   <NA>                       estimate 1.2998407
#> 23: 2020-03-15        R   <NA>                       estimate 1.2564185
#> 24: 2020-03-16        R   <NA>                       estimate 1.2157474
#> 25: 2020-03-17        R   <NA>                       estimate 1.1767008
#> 26: 2020-03-18        R   <NA>                       estimate 1.1391538
#> 27: 2020-03-19        R   <NA> estimate based on partial data 1.1026860
#> 28: 2020-03-20        R   <NA> estimate based on partial data 1.0681474
#> 29: 2020-03-21        R   <NA> estimate based on partial data 1.0369132
#> 30: 2020-03-22        R   <NA> estimate based on partial data 1.0076814
#> 31: 2020-03-23        R   <NA> estimate based on partial data 0.9796594
#> 32: 2020-03-24        R   <NA> estimate based on partial data 0.9532909
#> 33: 2020-03-25        R   <NA> estimate based on partial data 0.9295425
#> 34: 2020-03-26        R   <NA> estimate based on partial data 0.9075957
#> 35: 2020-03-27        R   <NA> estimate based on partial data 0.8870259
#> 36: 2020-03-28        R   <NA> estimate based on partial data 0.8670115
#> 37: 2020-03-29        R   <NA> estimate based on partial data 0.8487940
#> 38: 2020-03-30        R   <NA> estimate based on partial data 0.8337049
#> 39: 2020-03-31        R   <NA> estimate based on partial data 0.8198761
#> 40: 2020-04-01        R   <NA> estimate based on partial data 0.8090509
#> 41: 2020-04-02        R   <NA>                       forecast 0.8090509
#> 42: 2020-04-03        R   <NA>                       forecast 0.8090509
#> 43: 2020-04-04        R   <NA>                       forecast 0.8090509
#> 44: 2020-04-05        R   <NA>                       forecast 0.8090509
#> 45: 2020-04-06        R   <NA>                       forecast 0.8090509
#> 46: 2020-04-07        R   <NA>                       forecast 0.8090509
#> 47: 2020-04-08        R   <NA>                       forecast 0.8090509
#>           date variable  strat                           type    median
#>          mean         sd  lower_90  lower_50  lower_20  upper_20  upper_50
#>         <num>      <num>     <num>     <num>     <num>     <num>     <num>
#>  1: 2.0972401 0.08675670 1.9589946 2.0351368 2.0733334 2.1180630 2.1542747
#>  2: 2.0789848 0.07906350 1.9521136 2.0237378 2.0575485 2.0984831 2.1327527
#>  3: 2.0582801 0.07294917 1.9395774 2.0073726 2.0368343 2.0764405 2.1089502
#>  4: 2.0350017 0.06848612 1.9250198 1.9864038 2.0166798 2.0521817 2.0819388
#>  5: 2.0090579 0.06552534 1.9032990 1.9635058 1.9905285 2.0254098 2.0533511
#>  6: 1.9804027 0.06372819 1.8767779 1.9376283 1.9632087 1.9976259 2.0238092
#>  7: 1.9490473 0.06267418 1.8481341 1.9055878 1.9324007 1.9652150 1.9909910
#>  8: 1.9150656 0.06198072 1.8153409 1.8713633 1.8989990 1.9295272 1.9561491
#>  9: 1.8785950 0.06137029 1.7804782 1.8357375 1.8613070 1.8926327 1.9181492
#> 10: 1.8398313 0.06067330 1.7442895 1.7969423 1.8211358 1.8538923 1.8780636
#> 11: 1.7990189 0.05979646 1.7066933 1.7567188 1.7807051 1.8137154 1.8372261
#> 12: 1.7564390 0.05869237 1.6665561 1.7134966 1.7385937 1.7700389 1.7942929
#> 13: 1.7123975 0.05734737 1.6222849 1.6722727 1.6945498 1.7261003 1.7496817
#> 14: 1.6672130 0.05578274 1.5782299 1.6279726 1.6509647 1.6806198 1.7038488
#> 15: 1.6212071 0.05405391 1.5347867 1.5836514 1.6049468 1.6337913 1.6558731
#> 16: 1.5746954 0.05223786 1.4911820 1.5378972 1.5594379 1.5871399 1.6089526
#> 17: 1.5279815 0.05041263 1.4465868 1.4925324 1.5131385 1.5399251 1.5618143
#> 18: 1.4813530 0.04864285 1.4038469 1.4477254 1.4670463 1.4929531 1.5135944
#> 19: 1.4350797 0.04698316 1.3596699 1.4024167 1.4217781 1.4464161 1.4659600
#> 20: 1.3894143 0.04549868 1.3158144 1.3583252 1.3768114 1.4008862 1.4197155
#> 21: 1.3445925 0.04428886 1.2731041 1.3152499 1.3318268 1.3559661 1.3735009
#> 22: 1.3008339 0.04349614 1.2303796 1.2720825 1.2888079 1.3110276 1.3293265
#> 23: 1.2583410 0.04328861 1.1893881 1.2296423 1.2468304 1.2679551 1.2864223
#> 24: 1.2172975 0.04382131 1.1476454 1.1879973 1.2048353 1.2269465 1.2458028
#> 25: 1.1778664 0.04519619 1.1076483 1.1469630 1.1661060 1.1871116 1.2066289
#> 26: 1.1401875 0.04744344 1.0670304 1.1079290 1.1272572 1.1503024 1.1703102
#> 27: 1.1043763 0.05053057 1.0246666 1.0703471 1.0903128 1.1156618 1.1364077
#> 28: 1.0705231 0.05438566 0.9840139 1.0349136 1.0558128 1.0829502 1.1048249
#> 29: 1.0386927 0.05891748 0.9444090 0.9988392 1.0211832 1.0525112 1.0758524
#> 30: 1.0089248 0.06402592 0.9077921 0.9650266 0.9899737 1.0242957 1.0495250
#> 31: 0.9812343 0.06960669 0.8701173 0.9328365 0.9599324 0.9984305 1.0267990
#> 32: 0.9556138 0.07555573 0.8371090 0.9017816 0.9335641 0.9739453 1.0052472
#> 33: 0.9320355 0.08177454 0.8033826 0.8742907 0.9083900 0.9514522 0.9865505
#> 34: 0.9104553 0.08817473 0.7716468 0.8491871 0.8851391 0.9312314 0.9701883
#> 35: 0.8908155 0.09467897 0.7424957 0.8244023 0.8628602 0.9116651 0.9545728
#> 36: 0.8730486 0.10121805 0.7149979 0.8029721 0.8436376 0.8945351 0.9413963
#> 37: 0.8570795 0.10772560 0.6873213 0.7822403 0.8252138 0.8809368 0.9283431
#> 38: 0.8428276 0.11413344 0.6639840 0.7646281 0.8090548 0.8685974 0.9166273
#> 39: 0.8302088 0.12036969 0.6408544 0.7485375 0.7943009 0.8574678 0.9061648
#> 40: 0.8191379 0.12636016 0.6203508 0.7353379 0.7805685 0.8488279 0.8981959
#> 41: 0.8191379 0.12636016 0.6203508 0.7353379 0.7805685 0.8488279 0.8981959
#> 42: 0.8191379 0.12636016 0.6203508 0.7353379 0.7805685 0.8488279 0.8981959
#> 43: 0.8191379 0.12636016 0.6203508 0.7353379 0.7805685 0.8488279 0.8981959
#> 44: 0.8191379 0.12636016 0.6203508 0.7353379 0.7805685 0.8488279 0.8981959
#> 45: 0.8191379 0.12636016 0.6203508 0.7353379 0.7805685 0.8488279 0.8981959
#> 46: 0.8191379 0.12636016 0.6203508 0.7353379 0.7805685 0.8488279 0.8981959
#> 47: 0.8191379 0.12636016 0.6203508 0.7353379 0.7805685 0.8488279 0.8981959
#>          mean         sd  lower_90  lower_50  lower_20  upper_20  upper_50
#>     upper_90
#>        <num>
#>  1: 2.243183
#>  2: 2.213302
#>  3: 2.180841
#>  4: 2.147286
#>  5: 2.117325
#>  6: 2.088520
#>  7: 2.054906
#>  8: 2.019384
#>  9: 1.982714
#> 10: 1.943283
#> 11: 1.899806
#> 12: 1.854027
#> 13: 1.806421
#> 14: 1.760097
#> 15: 1.710677
#> 16: 1.660924
#> 17: 1.612651
#> 18: 1.564576
#> 19: 1.515342
#> 20: 1.463342
#> 21: 1.416475
#> 22: 1.370892
#> 23: 1.330251
#> 24: 1.291988
#> 25: 1.256505
#> 26: 1.222521
#> 27: 1.189304
#> 28: 1.162776
#> 29: 1.139987
#> 30: 1.116886
#> 31: 1.098449
#> 32: 1.081061
#> 33: 1.068088
#> 34: 1.058672
#> 35: 1.051671
#> 36: 1.045070
#> 37: 1.041859
#> 38: 1.040326
#> 39: 1.036806
#> 40: 1.033875
#> 41: 1.033875
#> 42: 1.033875
#> 43: 1.033875
#> 44: 1.033875
#> 45: 1.033875
#> 46: 1.033875
#> 47: 1.033875
#>     upper_90

options(old_opts)
# }