Skip to contents

Real-time Rt Estimation, Forecasting and Reporting by Region

Source: R/regional_epinow.R
regional_epinow.Rd

[Maturing] Efficiently runs epinow() across multiple regions in an efficient manner and conducts basic data checks and cleaning such as removing regions with fewer than non_zero_points as these are unlikely to produce reasonable results whilst consuming significant resources. See the documentation for epinow() for further information.

By default all arguments supporting input from _opts() functions are shared across regions (including delays, truncation, Rt settings, stan settings, and gaussian process settings). Region specific settings are supported by passing a named list of _opts() calls (with an entry per region) to the relevant argument. A helper function (opts_list()) is available to facilitate building this list.

Regions can be estimated in parallel using the {future} package (see setup_future()). The progress of producing estimates across multiple regions can be tracked using the {progressr} package. Modify this behaviour using progressr::handlers() and enable it in batch by setting R_PROGRESSR_ENABLE=TRUE as an environment variable.

Usage

regional_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),
  target_folder = NULL,
  target_date,
  non_zero_points = 2,
  output = c("regions", "summary", "samples", "plots", "latest"),
  return_output = is.null(target_folder),
  summary_args = list(),
  verbose = FALSE,
  logs = tempdir(check = TRUE),
  ...
)

Arguments

data

A <data.frame> of disease reports (confirm) by date (date), and region (region).

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 done.

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.

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.

non_zero_points

Numeric, the minimum number of time points with non-zero cases in a region required for that region to be evaluated. Defaults to 7.

output

A character vector of optional output to return. Supported options are the individual regional estimates ("regions"), samples ("samples"), plots ("plots"), copying the individual region dated folder into a latest folder (if target_folder is not null, set using "latest"), the stan fit of the underlying model ("fit"), and an overall summary across regions ("summary"). The default is to return samples and plots alongside summarised estimates and summary statistics. If target_folder is not NULL then the default is also to copy all results into a latest folder.

return_output

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

summary_args

A list of arguments passed to regional_summary(). See the regional_summary() documentation for details.

verbose

Logical defaults to FALSE. Outputs verbose progress messages to the console from epinow().

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.

...

Pass additional arguments to epinow(). See the documentation for epinow() for details.

Value

A list of output stratified at the top level into regional output and across region output summary output

See also

epinow() estimate_infections() setup_future() regional_summary()

Examples

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

# uses example case vector
cases <- example_confirmed[1:60]
cases <- data.table::rbindlist(list(
  data.table::copy(cases)[, region := "testland"],
  cases[, region := "realland"]
))

# run epinow across multiple regions and generate summaries
# samples and warmup have been reduced for this example
# for more examples, see the "estimate_infections examples" vignette
def <- regional_epinow(
  data = cases,
  generation_time = gt_opts(example_generation_time),
  delays = delay_opts(example_incubation_period + example_reporting_delay),
  rt = rt_opts(prior = LogNormal(mean = 2, sd = 0.2)),
  stan = stan_opts(
    samples = 100, warmup = 200
  ),
  verbose = interactive()
)
#> INFO [2025-05-06 11:22:58] Producing following optional outputs: regions, summary, samples, plots, latest
#> Logging threshold set at INFO for the name logger
#> Writing EpiNow2 logs to the console and:
#> /tmp/RtmpW1P4Hk/regional-epinow/2020-04-21.log.
#> Logging threshold set at INFO for the name logger
#> Writing EpiNow2.epinow logs to: /tmp/RtmpW1P4Hk/epinow/2020-04-21.log.
#> INFO [2025-05-06 11:22:58] Reporting estimates using data up to: 2020-04-21
#> INFO [2025-05-06 11:22:58] No target directory specified so returning output
#> INFO [2025-05-06 11:22:58] Producing estimates for: testland, realland
#> INFO [2025-05-06 11:22:58] Regions excluded: none
#> INFO [2025-05-06 11:24:11] Completed estimates for: testland
#> INFO [2025-05-06 11:25:30] Completed estimates for: realland
#> INFO [2025-05-06 11:25:30] Completed regional estimates
#> INFO [2025-05-06 11:25:30] Regions with estimates: 2
#> INFO [2025-05-06 11:25:30] Regions with runtime errors: 0
#> INFO [2025-05-06 11:25:30] Producing summary
#> INFO [2025-05-06 11:25:30] No summary directory specified so returning summary output
#> INFO [2025-05-06 11:25:30] No target directory specified so returning timings
options(old_opts)
# }