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(),
stan = stan_opts(),
horizon = 7,
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 anddate
must be in date format.- generation_time
A call to
gt_opts()
(or its aliasgeneration_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 ofdelay_opts()
and the examples below for details.- truncation
A call to
trunc_opts()
defining the truncation of the observed data. Defaults totrunc_opts()
, i.e. no truncation. See theestimate_truncation()
help file for an approach to estimating this from data where thedist
list element returned byestimate_truncation()
is used as thetruncation
argument here, thereby propagating the uncertainty in the estimate.- rt
A list of options as generated by
rt_opts()
defining Rt estimation. Defaults tort_opts()
. To generate new infections using the non-mechanistic model instead of the renewal equation model, usert = NULL
. The non-mechanistic model internally uses the settingrt = 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 tobackcalc_opts()
.- gp
A list of options as generated by
gp_opts()
to define the Gaussian process. Defaults togp_opts()
. Set toNULL
to disable the Gaussian process.- obs
A list of options as generated by
obs_opts()
defining the observation model. Defaults toobs_opts()
.- stan
A list of stan options as generated by
stan_opts()
. Defaults tostan_opts()
. Can be used to overridedata
,init
, andverbose
settings if desired.- horizon
Numeric, defaults to 7. Number of days into the future to forecast.
- 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 forsetup_default_logging()
and thesetup_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 otherwiseFALSE
. Should verbose debug progress messages be printed. Corresponds to the "DEBUG" level fromfutile.logger
. Seesetup_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.
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 = list(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/RtmpowyJHs/regional-epinow/2020-04-01.log.
#> Logging threshold set at INFO for the name logger
#> Writing EpiNow2.epinow logs to the console and:
#> /tmp/RtmpowyJHs/epinow/2020-04-01.log.
#> WARN [2024-10-03 12:07:00] epinow: There were 1 divergent transitions after warmup. See
#> https://mc-stan.org/misc/warnings.html#divergent-transitions-after-warmup
#> to find out why this is a problem and how to eliminate them. -
#> WARN [2024-10-03 12:07:00] epinow: Examine the pairs() plot to diagnose sampling problems
#> -
# summary of the latest estimates
summary(out)
#> measure estimate
#> <char> <char>
#> 1: New infections per day 3720 (1914 -- 7282)
#> 2: Expected change in daily reports Likely decreasing
#> 3: Effective reproduction no. 0.82 (0.63 -- 1)
#> 4: Rate of growth -0.06 (-0.13 -- 0.012)
#> 5: Doubling/halving time (days) -11 (58 -- -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.1004262
#> 2: 2020-02-23 R <NA> estimate 2.0826880
#> 3: 2020-02-24 R <NA> estimate 2.0615412
#> 4: 2020-02-25 R <NA> estimate 2.0374484
#> 5: 2020-02-26 R <NA> estimate 2.0103524
#> 6: 2020-02-27 R <NA> estimate 1.9806491
#> 7: 2020-02-28 R <NA> estimate 1.9484219
#> 8: 2020-02-29 R <NA> estimate 1.9130309
#> 9: 2020-03-01 R <NA> estimate 1.8759962
#> 10: 2020-03-02 R <NA> estimate 1.8369330
#> 11: 2020-03-03 R <NA> estimate 1.7948678
#> 12: 2020-03-04 R <NA> estimate 1.7515767
#> 13: 2020-03-05 R <NA> estimate 1.7085943
#> 14: 2020-03-06 R <NA> estimate 1.6633600
#> 15: 2020-03-07 R <NA> estimate 1.6176109
#> 16: 2020-03-08 R <NA> estimate 1.5720028
#> 17: 2020-03-09 R <NA> estimate 1.5253205
#> 18: 2020-03-10 R <NA> estimate 1.4796013
#> 19: 2020-03-11 R <NA> estimate 1.4332459
#> 20: 2020-03-12 R <NA> estimate 1.3875692
#> 21: 2020-03-13 R <NA> estimate 1.3426551
#> 22: 2020-03-14 R <NA> estimate 1.2985542
#> 23: 2020-03-15 R <NA> estimate 1.2567384
#> 24: 2020-03-16 R <NA> estimate 1.2153597
#> 25: 2020-03-17 R <NA> estimate 1.1768714
#> 26: 2020-03-18 R <NA> estimate 1.1386682
#> 27: 2020-03-19 R <NA> estimate based on partial data 1.1027276
#> 28: 2020-03-20 R <NA> estimate based on partial data 1.0685297
#> 29: 2020-03-21 R <NA> estimate based on partial data 1.0375340
#> 30: 2020-03-22 R <NA> estimate based on partial data 1.0086124
#> 31: 2020-03-23 R <NA> estimate based on partial data 0.9818702
#> 32: 2020-03-24 R <NA> estimate based on partial data 0.9567490
#> 33: 2020-03-25 R <NA> estimate based on partial data 0.9334786
#> 34: 2020-03-26 R <NA> estimate based on partial data 0.9114745
#> 35: 2020-03-27 R <NA> estimate based on partial data 0.8912774
#> 36: 2020-03-28 R <NA> estimate based on partial data 0.8746998
#> 37: 2020-03-29 R <NA> estimate based on partial data 0.8583870
#> 38: 2020-03-30 R <NA> estimate based on partial data 0.8432416
#> 39: 2020-03-31 R <NA> estimate based on partial data 0.8293520
#> 40: 2020-04-01 R <NA> estimate based on partial data 0.8185555
#> 41: 2020-04-02 R <NA> forecast 0.8185555
#> 42: 2020-04-03 R <NA> forecast 0.8185555
#> 43: 2020-04-04 R <NA> forecast 0.8185555
#> 44: 2020-04-05 R <NA> forecast 0.8185555
#> 45: 2020-04-06 R <NA> forecast 0.8185555
#> 46: 2020-04-07 R <NA> forecast 0.8185555
#> 47: 2020-04-08 R <NA> forecast 0.8185555
#> 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.1016365 0.08622363 1.9584114 2.0464520 2.0806129 2.1221625 2.1548502
#> 2: 2.0828319 0.07830160 1.9498320 2.0320006 2.0643645 2.1011968 2.1316310
#> 3: 2.0616321 0.07203226 1.9423773 2.0133001 2.0444054 2.0806158 2.1069900
#> 4: 2.0379206 0.06751003 1.9273578 1.9917118 2.0215805 2.0541537 2.0817805
#> 5: 2.0116085 0.06458920 1.9067178 1.9680898 1.9954626 2.0248812 2.0549684
#> 6: 1.9826490 0.06291314 1.8822706 1.9393073 1.9656287 1.9961278 2.0246164
#> 7: 1.9510482 0.06203048 1.8531071 1.9091274 1.9329610 1.9637939 1.9935357
#> 8: 1.9168720 0.06152497 1.8192808 1.8755276 1.8997586 1.9286938 1.9566684
#> 9: 1.8802470 0.06108694 1.7857597 1.8391199 1.8617283 1.8929880 1.9199496
#> 10: 1.8413564 0.06051589 1.7465378 1.8013637 1.8218627 1.8534366 1.8804496
#> 11: 1.8004312 0.05968861 1.7084020 1.7603470 1.7816975 1.8113649 1.8391626
#> 12: 1.7577395 0.05853081 1.6675314 1.7180722 1.7382880 1.7682017 1.7963904
#> 13: 1.7135753 0.05700970 1.6260996 1.6748316 1.6950209 1.7229404 1.7514226
#> 14: 1.6682488 0.05514231 1.5839926 1.6300541 1.6494103 1.6782868 1.7038065
#> 15: 1.6220769 0.05300293 1.5408708 1.5842681 1.6040862 1.6331409 1.6570410
#> 16: 1.5753762 0.05071578 1.4973320 1.5389401 1.5586722 1.5859775 1.6082515
#> 17: 1.5284565 0.04843057 1.4542490 1.4932191 1.5138489 1.5392335 1.5605958
#> 18: 1.4816167 0.04629144 1.4119681 1.4480947 1.4679174 1.4915866 1.5121551
#> 19: 1.4351418 0.04441542 1.3671450 1.4036684 1.4214594 1.4451062 1.4645564
#> 20: 1.3893015 0.04289166 1.3228481 1.3590930 1.3763463 1.3987266 1.4177228
#> 21: 1.3443491 0.04179864 1.2795138 1.3146710 1.3321990 1.3528509 1.3715775
#> 22: 1.3005196 0.04122330 1.2361566 1.2718977 1.2896335 1.3087837 1.3257804
#> 23: 1.2580280 0.04126554 1.1930197 1.2297512 1.2469097 1.2660029 1.2829763
#> 24: 1.2170659 0.04202364 1.1512689 1.1880482 1.2060157 1.2264589 1.2428055
#> 25: 1.1777984 0.04357137 1.1097299 1.1484862 1.1659315 1.1870416 1.2047470
#> 26: 1.1403618 0.04594269 1.0665436 1.1098086 1.1276184 1.1494409 1.1696466
#> 27: 1.1048619 0.04913018 1.0243034 1.0730140 1.0902221 1.1147133 1.1359996
#> 28: 1.0713740 0.05309192 0.9846129 1.0363654 1.0565467 1.0810648 1.1044246
#> 29: 1.0399434 0.05775853 0.9486541 1.0016848 1.0235665 1.0513505 1.0760646
#> 30: 1.0105874 0.06303830 0.9107250 0.9683588 0.9943236 1.0230021 1.0495387
#> 31: 0.9832977 0.06882343 0.8737751 0.9374104 0.9650516 0.9974886 1.0263811
#> 32: 0.9580449 0.07499952 0.8397988 0.9092514 0.9380268 0.9732099 1.0047233
#> 33: 0.9347828 0.08145682 0.8044129 0.8801741 0.9132415 0.9516857 0.9859760
#> 34: 0.9134533 0.08809934 0.7729076 0.8541724 0.8907679 0.9326046 0.9686929
#> 35: 0.8939914 0.09484834 0.7442596 0.8285095 0.8707017 0.9150246 0.9531643
#> 36: 0.8763286 0.10163936 0.7166470 0.8062669 0.8515070 0.8996673 0.9399348
#> 37: 0.8603952 0.10841506 0.6876217 0.7850552 0.8336141 0.8846204 0.9270296
#> 38: 0.8461209 0.11511774 0.6653146 0.7659223 0.8176221 0.8708647 0.9154611
#> 39: 0.8334357 0.12168480 0.6418453 0.7478240 0.8021602 0.8592726 0.9059520
#> 40: 0.8222693 0.12804814 0.6255871 0.7318509 0.7899030 0.8477374 0.8979333
#> 41: 0.8222693 0.12804814 0.6255871 0.7318509 0.7899030 0.8477374 0.8979333
#> 42: 0.8222693 0.12804814 0.6255871 0.7318509 0.7899030 0.8477374 0.8979333
#> 43: 0.8222693 0.12804814 0.6255871 0.7318509 0.7899030 0.8477374 0.8979333
#> 44: 0.8222693 0.12804814 0.6255871 0.7318509 0.7899030 0.8477374 0.8979333
#> 45: 0.8222693 0.12804814 0.6255871 0.7318509 0.7899030 0.8477374 0.8979333
#> 46: 0.8222693 0.12804814 0.6255871 0.7318509 0.7899030 0.8477374 0.8979333
#> 47: 0.8222693 0.12804814 0.6255871 0.7318509 0.7899030 0.8477374 0.8979333
#> mean sd lower_90 lower_50 lower_20 upper_20 upper_50
#> upper_90
#> <num>
#> 1: 2.247510
#> 2: 2.215100
#> 3: 2.182025
#> 4: 2.151547
#> 5: 2.117165
#> 6: 2.086123
#> 7: 2.054430
#> 8: 2.022343
#> 9: 1.986336
#> 10: 1.945477
#> 11: 1.904564
#> 12: 1.862815
#> 13: 1.814346
#> 14: 1.765030
#> 15: 1.713791
#> 16: 1.663327
#> 17: 1.611861
#> 18: 1.562054
#> 19: 1.509924
#> 20: 1.462279
#> 21: 1.417130
#> 22: 1.371892
#> 23: 1.330935
#> 24: 1.290604
#> 25: 1.253780
#> 26: 1.220349
#> 27: 1.190787
#> 28: 1.164106
#> 29: 1.141356
#> 30: 1.119950
#> 31: 1.103817
#> 32: 1.089415
#> 33: 1.076420
#> 34: 1.067038
#> 35: 1.056563
#> 36: 1.049848
#> 37: 1.045004
#> 38: 1.043859
#> 39: 1.047604
#> 40: 1.045867
#> 41: 1.045867
#> 42: 1.045867
#> 43: 1.045867
#> 44: 1.045867
#> 45: 1.045867
#> 46: 1.045867
#> 47: 1.045867
#> upper_90
options(old_opts)
# }