Package 'EpiNow2'

Description

Usage

## S3 method for class 'dist_spec'
e1 + e2

Arguments

Value

A delay distribution representing the sum of the two delays

Examples

# A fixed lognormal distribution with mean 5 and sd 1.
dist1 <- LogNormal(
  meanlog = 1.6, sdlog = 1, max = 20
)
dist1 + dist1

# An uncertain gamma distribution with mean 3 and sd 2
dist2 <- Gamma(
  mean = Normal(3, 0.5), sd = Normal(2, 0.5), max = 20
)
dist1 + dist2

Description

Defines a list specifying the optional arguments for the back calculation of cases. Only used if rt = NULL.

Usage

backcalc_opts(
  prior = c("reports", "none", "infections"),
  prior_window = 14,
  rt_window = 1
)

Arguments

Value

A ⁠<backcalc_opts>⁠ object of back calculation settings.

Examples

# default settings
backcalc_opts()

Description

Fits an integer adjusted distribution to a subsampled bootstrap of data and then integrates the posterior samples into a single set of summary statistics. Can be used to generate a robust reporting delay that accounts for the fact the underlying delay likely varies over time or that the size of the available reporting delay sample may not be representative of the current case load.

Usage

bootstrapped_dist_fit(
  values,
  dist = "lognormal",
  samples = 2000,
  bootstraps = 10,
  bootstrap_samples = 250,
  max_value,
  verbose = FALSE
)

Arguments

Value

A ⁠<dist_spec>⁠ object summarising the bootstrapped distribution

Examples

# lognormal
delays <- rlnorm(500, log(5), 1)
out <- bootstrapped_dist_fit(delays,
  samples = 1000, bootstraps = 10,
  dist = "lognormal"
)
out

Description

This sets attributes for further processing

Usage

bound_dist(x, max = Inf, cdf_cutoff = 0)

Arguments

Value

a ⁠<dist_spec>⁠ with relevant attributes set that define its bounds

Description

This combines the parameters so that they can be fed as multiple delay distributions to epinow() or estimate_infections().

Note that distributions that already are combinations of other distributions cannot be combined with other combinations of distributions.

Usage

## S3 method for class 'dist_spec'
c(...)

Arguments

Value

Combined delay distributions (with class ⁠<dist_spec>⁠)

Examples

# A fixed lognormal distribution with mean 5 and sd 1.
dist1 <- LogNormal(
  meanlog = 1.6, sdlog = 1, max = 20
)
dist1 + dist1

# An uncertain gamma distribution with mean 3 and sd 2
dist2 <- Gamma(
  mean = Normal(3, 0.5), sd = Normal(2, 0.5), max = 20
)
c(dist1, dist2)

Description

Adds symmetric a credible interval based on quantiles.

Usage

calc_CrI(samples, summarise_by = NULL, CrI = 0.9)

Arguments

Value

A data.table containing the upper and lower bounds for the specified credible interval.

Examples

samples <- data.frame(value = 1:10, type = "car")
# add 90% credible interval
calc_CrI(samples)
# add 90% credible interval grouped by type
calc_CrI(samples, summarise_by = "type")

Description

Adds symmetric credible intervals based on quantiles.

Usage

calc_CrIs(samples, summarise_by = NULL, CrIs = c(0.2, 0.5, 0.9))

Arguments

Value

A data.table containing the summarise_by variables and the specified lower and upper credible intervals.

Examples

samples <- data.frame(value = 1:10, type = "car")
# add credible intervals
calc_CrIs(samples)
# add 90% credible interval grouped by type
calc_CrIs(samples, summarise_by = "type")

Description

Calculate summary statistics and credible intervals from a ⁠<data.frame>⁠ by group.

Usage

calc_summary_measures(
  samples,
  summarise_by = NULL,
  order_by = NULL,
  CrIs = c(0.2, 0.5, 0.9)
)

Arguments

Value

A data.table containing summary statistics by group.

Examples

samples <- data.frame(value = 1:10, type = "car")
# default
calc_summary_measures(samples)
#  by type
calc_summary_measures(samples, summarise_by = "type")

Description

Calculate summary statistics from a ⁠<data.frame>⁠ by group. Currently supports the mean, median and standard deviation.

Usage

calc_summary_stats(samples, summarise_by = NULL)

Arguments

Value

A data.table containing the upper and lower bounds for the specified credible interval

Examples

samples <- data.frame(value = 1:10, type = "car")
# default
calc_summary_stats(samples)
#  by type
calc_summary_stats(samples, summarise_by = "type")

Description

This function removes nowcasts in the format produced by EpiNow2 from a target directory for the date supplied.

Usage

clean_nowcasts(date = Sys.Date(), nowcast_dir = ".")

Arguments

Value

No return value, called for side effects

Description

Removes regions with insufficient time points, and provides logging information on the input.

Usage

clean_regions(data, non_zero_points)

Arguments

Value

A dataframe of cleaned regional data

See Also

regional_epinow()

Description

This convolves any consecutive nonparametric distributions contained in the <dist_spec>.

Usage

## S3 method for class 'dist_spec'
collapse(x, ...)

Arguments

Value

A ⁠<dist_spec>⁠ where consecutive nonparametric distributions have been convolved

Examples

# A fixed gamma distribution with mean 5 and sd 1.
dist1 <- Gamma(mean = 5, sd = 1, max = 20)

# An uncertain lognormal distribution with mean 3 and sd 2
dist2 <- LogNormal(mean = 3, sd = 2, max = 20)

# The maxf the sum of two distributions
collapse(discretise(dist1 + dist2))

Description

Convert from mean and standard deviation to the log mean of the lognormal distribution. Useful for defining distributions supported by estimate_infections(), epinow(), and regional_epinow().

Usage

convert_to_logmean(mean, sd)

Arguments

Value

The log mean of a lognormal distribution

Examples

convert_to_logmean(2, 1)

Description

Convert from mean and standard deviation to the log standard deviation of the lognormal distribution. Useful for defining distributions supported by estimate_infections(), epinow(), and regional_epinow().

Usage

convert_to_logsd(mean, sd)

Arguments

Value

The log standard deviation of a lognormal distribution

Examples

convert_to_logsd(2, 1)

Description

This applies a lognormal convolution with given, potentially time-varying parameters representing the parameters of the lognormal distribution used for the convolution and an optional scaling factor. This is akin to the model used in estimate_secondary() and simulate_secondary().

Usage

convolve_and_scale(
  data,
  type = c("incidence", "prevalence"),
  family = c("none", "poisson", "negbin"),
  delay_max = 30,
  ...
)

Arguments

Details

Up to version 1.4.0 this function was called simulate_secondary().

Value

A ⁠<data.frame>⁠ containing simulated data in the format required by estimate_secondary().

See Also

estimate_secondary

Examples

# load data.table for manipulation
library(data.table)

#### Incidence data example ####

# make some example secondary incidence data
cases <- example_confirmed
cases <- as.data.table(cases)[, primary := confirm]

# Assume that only 40 percent of cases are reported
cases[, scaling := 0.4]

# Parameters of the assumed log normal delay distribution
cases[, meanlog := 1.8][, sdlog := 0.5]

# Simulate secondary cases
cases <- convolve_and_scale(cases, type = "incidence")
cases
#### Prevalence data example ####

# make some example prevalence data
cases <- example_confirmed
cases <- as.data.table(cases)[, primary := confirm]

# Assume that only 30 percent of cases are reported
cases[, scaling := 0.3]

# Parameters of the assumed log normal delay distribution
cases[, meanlog := 1.6][, sdlog := 0.8]

# Simulate secondary cases
cases <- convolve_and_scale(cases, type = "prevalence")
cases

Description

Returns delay distributions formatted for usage by downstream functions.

Usage

delay_opts(
  dist = Fixed(0),
  ...,
  fixed = FALSE,
  default_cdf_cutoff = 0.001,
  weight_prior = TRUE
)

Arguments

Value

A ⁠<delay_opts>⁠ object summarising the input delay distributions.

See Also

convert_to_logmean() convert_to_logsd() bootstrapped_dist_fit() Distributions

Examples

# no delays
delay_opts()

# A single delay that has uncertainty
delay <- LogNormal(mean = Normal(1, 0.2), sd = Normal(0.5, 0.1), max = 14)
delay_opts(delay)

# A single delay without uncertainty
delay <- LogNormal(meanlog = 1, sdlog = 0.5, max = 14)
delay_opts(delay)

# Multiple delays (in this case twice the same)
delay_opts(delay + delay)

Description

Usage

## S3 method for class 'dist_spec'
discretise(x, strict = TRUE, ...)

discretize(x, ...)

Arguments

Value

A ⁠<dist_spec>⁠ where all distributions with constant parameters are nonparametric.

Methodological details

The probability mass function of the discretised probability distribution is a vector where the first entry corresponds to the integral over the (0,1] interval of the corresponding continuous distribution (probability of integer 0), the second entry corresponds to the (0,2] interval (probability mass of integer 1), the third entry corresponds to the (1, 3] interval (probability mass of integer 2), etc. This approximates the true probability mass function of a double censored distribution which arises from the difference of two censored events.

References

Charniga, K., et al. “Best practices for estimating and reporting epidemiological delay distributions of infectious diseases using public health surveillance and healthcare data”, arXiv e-prints, 2024. doi:10.48550/arXiv.2405.08841 Park, S. W., et al., "Estimating epidemiological delay distributions for infectious diseases", medRxiv, 2024. doi:10.1101/2024.01.12.24301247

Examples

# A fixed gamma distribution with mean 5 and sd 1.
dist1 <- Gamma(mean = 5, sd = 1, max = 20)

# An uncertain lognormal distribution with mean 3 and sd 2
dist2 <- LogNormal(mean = Normal(3, 0.5), sd = Normal(2, 0.5), max = 20)

# The maxf the sum of two distributions
discretise(dist1 + dist2, strict = FALSE)

Description

Fits an integer adjusted exponential, gamma or lognormal distribution using stan.

Usage

dist_fit(
  values = NULL,
  samples = 1000,
  cores = 1,
  chains = 2,
  dist = "exp",
  verbose = FALSE,
  backend = "rstan"
)

Arguments

Value

A stan fit of an interval censored distribution

Examples

# integer adjusted exponential model
dist_fit(rexp(1:100, 2),
  samples = 1000, dist = "exp",
  cores = ifelse(interactive(), 4, 1), verbose = TRUE
)


# integer adjusted gamma model
dist_fit(rgamma(1:100, 5, 5),
  samples = 1000, dist = "gamma",
  cores = ifelse(interactive(), 4, 1), verbose = TRUE
)

# integer adjusted lognormal model
dist_fit(rlnorm(1:100, log(5), 0.2),
  samples = 1000, dist = "lognormal",
  cores = ifelse(interactive(), 4, 1), verbose = TRUE
)

Description

Probability distributions

Generates a nonparametric distribution.

Usage

LogNormal(meanlog, sdlog, mean, sd, ...)

Gamma(shape, rate, scale, mean, sd, ...)

Normal(mean, sd, ...)

Fixed(value, ...)

NonParametric(pmf, ...)

Arguments

Details

Probability distributions are ubiquitous in EpiNow2, usually representing epidemiological delays (e.g., the generation time for delays between becoming infecting and infecting others; or reporting delays)

They are generated using functions that have a name corresponding to the probability distribution that is being used. They generated dist_spec objects that are then passed to the models underlying EpiNow2. All parameters can be given either as fixed values (a numeric value) or as uncertain values (a dist_sepc). If given as uncertain values, currently only normally distributed parameters (generated using Normal()) are supported.

Each distribution has a representation in terms of "natural" parameters (the ones used in stan) but can sometimes also be specified using other parameters such as the mean or standard deviation of the distribution. If not given as natural parameters then these will be calculated from the given parameters. If they have uncertainty, this will be done by random sampling from the given uncertainty and converting resulting parameters to their natural representation.

Currently available distributions are lognormal, gamma, normal, fixed (delta) and nonparametric. The nonparametric is a special case where the probability mass function is given directly as a numeric vector.

Value

A dist_spec representing a distribution of the given specification.

Examples

LogNormal(mean = 4, sd = 1)
LogNormal(mean = 4, sd = 1, max = 10)
LogNormal(mean = Normal(4, 1), sd = 1, max = 10)
Gamma(mean = 4, sd = 1)
Gamma(shape = 16, rate = 4)
Gamma(shape = Normal(16, 2), rate = Normal(4, 1))
Gamma(shape = Normal(16, 2), scale = Normal(1/4, 1))
Normal(mean = 4, sd = 1)
Normal(mean = 4, sd = 1, max = 10)
Fixed(value = 3)
Fixed(value = 3.5)
NonParametric(c(0.1, 0.3, 0.2, 0.4))
NonParametric(c(0.1, 0.3, 0.2, 0.1, 0.1))

Description

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

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

# 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)
)
# summary of the latest estimates
summary(out)
# plot estimates
plot(out)

# summary of R estimates
summary(out, type = "parameters", params = "R")

options(old_opts)

Description

The function has been adapted from a similar function in the epinowcast package (Copyright holder: epinowcast authors, under MIT License).

Usage

epinow2_cmdstan_model(
  model = "estimate_infections",
  dir = system.file("stan", package = "EpiNow2"),
  verbose = FALSE,
  ...
)

Arguments

Value

A cmdstanr model.

Description

Estimate a log normal delay distribution from a vector of integer delays. Currently this function is a simple wrapper for bootstrapped_dist_fit().

Usage

estimate_delay(delays, ...)

Arguments

Value

A ⁠<dist_spec>⁠ summarising the bootstrapped distribution

See Also

bootstrapped_dist_fit()

Examples

delays <- rlnorm(500, log(5), 1)
estimate_delay(delays, samples = 1000, bootstraps = 10)

Description

Uses a non-parametric approach to reconstruct cases by date of infection from reported cases. It uses either a generative Rt model or non-parametric back calculation to estimate underlying latent infections and then maps these infections to observed cases via uncertain reporting delays and a flexible observation model. See the examples and function arguments for the details of all options. The default settings may not be sufficient for your use case so the number of warmup samples (stan_args = list(warmup)) may need to be increased as may the overall number of samples. Follow the links provided by any warnings messages to diagnose issues with the MCMC fit. It is recommended to explore several of the Rt estimation approaches supported as not all of them may be suited to users own use cases. See here for an example of using estimate_infections within the epinow wrapper to estimate Rt for Covid-19 in a country from the ECDC data source.

Usage

estimate_infections(
  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,
  weigh_delay_priors = TRUE,
  id = "estimate_infections",
  verbose = interactive(),
  reported_cases
)

Arguments

Value

A list of output including: posterior samples, summarised posterior samples, data used to fit the model, and the fit object itself.

See Also

epinow() regional_epinow() forecast_infections() estimate_truncation()

Examples

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

# get example case counts
reported_cases <- example_confirmed[1:60]

# 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)

# for more examples, see the "estimate_infections examples" vignette
def <- estimate_infections(reported_cases,
  generation_time = gt_opts(generation_time),
  delays = delay_opts(incubation_period + reporting_delay),
  rt = rt_opts(prior = list(mean = 2, sd = 0.1))
)
# real time estimates
summary(def)
# summary plot
plot(def)
options(old_opts)

Description

Estimates the relationship between a primary and secondary observation, for example hospital admissions and deaths or hospital admissions and bed occupancy. See secondary_opts() for model structure options. See parameter documentation for model defaults and options. See the examples for case studies using synthetic data and here for an example of forecasting Covid-19 deaths from Covid-19 cases. See here for a prototype function that may be used to estimate and forecast a secondary observation from a primary across multiple regions and here # nolint for an application forecasting Covid-19 deaths in Germany and Poland.

Usage

estimate_secondary(
  data,
  secondary = secondary_opts(),
  delays = delay_opts(LogNormal(meanlog = Normal(2.5, 0.5), sdlog = Normal(0.47, 0.25),
    max = 30), weight_prior = FALSE),
  truncation = trunc_opts(),
  obs = obs_opts(),
  stan = stan_opts(),
  burn_in = 14,
  CrIs = c(0.2, 0.5, 0.9),
  filter_leading_zeros = FALSE,
  zero_threshold = Inf,
  priors = NULL,
  model = NULL,
  weigh_delay_priors = FALSE,
  verbose = interactive(),
  ...,
  reports
)

Arguments

Value

A list containing: predictions (a ⁠<data.frame>⁠ ordered by date with the primary, and secondary observations, and a summary of the model estimated secondary observations), posterior which contains a summary of the entire model posterior, data (a list of data used to fit the model), and fit (the stanfit object).

Examples

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

# load data.table for manipulation
library(data.table)

#### Incidence data example ####

# make some example secondary incidence data
cases <- example_confirmed
cases <- as.data.table(cases)[, primary := confirm]
# Assume that only 40 percent of cases are reported
cases[, scaling := 0.4]
# Parameters of the assumed log normal delay distribution
cases[, meanlog := 1.8][, sdlog := 0.5]

# Simulate secondary cases
cases <- convolve_and_scale(cases, type = "incidence")
#
# fit model to example data specifying a weak prior for fraction reported
# with a secondary case
inc <- estimate_secondary(cases[1:60],
  obs = obs_opts(scale = list(mean = 0.2, sd = 0.2), week_effect = FALSE)
)
plot(inc, primary = TRUE)

# forecast future secondary cases from primary
inc_preds <- forecast_secondary(
  inc, cases[seq(61, .N)][, value := primary]
)
plot(inc_preds, new_obs = cases, from = "2020-05-01")

#### Prevalence data example ####

# make some example prevalence data
cases <- example_confirmed
cases <- as.data.table(cases)[, primary := confirm]
# Assume that only 30 percent of cases are reported
cases[, scaling := 0.3]
# Parameters of the assumed log normal delay distribution
cases[, meanlog := 1.6][, sdlog := 0.8]

# Simulate secondary cases
cases <- convolve_and_scale(cases, type = "prevalence")

# fit model to example prevalence data
prev <- estimate_secondary(cases[1:100],
  secondary = secondary_opts(type = "prevalence"),
  obs = obs_opts(
    week_effect = FALSE,
    scale = list(mean = 0.4, sd = 0.1)
  )
)
plot(prev, primary = TRUE)

# forecast future secondary cases from primary
prev_preds <- forecast_secondary(
 prev, cases[seq(101, .N)][, value := primary]
)
plot(prev_preds, new_obs = cases, from = "2020-06-01")

options(old_opts)

Description

Estimates a truncation distribution from multiple snapshots of the same data source over time. This distribution can then be used passed to the truncation argument in regional_epinow(), epinow(), and estimate_infections() to adjust for truncated data and propagate the uncertainty associated with data truncation into the estimates.

See here for an example of using this approach on Covid-19 data in England. The functionality offered by this function is now available in a more principled manner in the epinowcast R package.

The model of truncation is as follows:

1. The truncation distribution is assumed to be discretised log normal wit a mean and standard deviation that is informed by the data.

2. The data set with the latest observations is adjusted for truncation using the truncation distribution.

3. Earlier data sets are recreated by applying the truncation distribution to the adjusted latest observations in the time period of the earlier data set. These data sets are then compared to the earlier observations assuming a negative binomial observation model with an additive noise term to deal with zero observations.

This model is then fit using stan with standard normal, or half normal, prior for the mean, standard deviation, 1 over the square root of the overdispersion and additive noise term.

This approach assumes that:

• Current truncation is related to past truncation.

• Truncation is a multiplicative scaling of underlying reported cases.

• Truncation is log normally distributed.

Usage

estimate_truncation(
  data,
  truncation = trunc_opts(LogNormal(meanlog = Normal(0, 1), sdlog = Normal(1, 1), max =
    10)),
  model = NULL,
  stan = stan_opts(),
  CrIs = c(0.2, 0.5, 0.9),
  filter_leading_zeros = FALSE,
  zero_threshold = Inf,
  weigh_delay_priors = FALSE,
  verbose = TRUE,
  ...,
  obs
)

Arguments

Value

A list containing: the summary parameters of the truncation distribution (dist), which could be passed to the truncation argument of epinow(), regional_epinow(), and estimate_infections(), the estimated CMF of the truncation distribution (cmf, can be used to adjusted new data), a ⁠<data.frame>⁠ containing the observed truncated data, latest observed data and the adjusted for truncation observations (obs), a ⁠<data.frame>⁠ containing the last observed data (last_obs, useful for plotting and validation), the data used for fitting (data) and the fit object (fit).

Examples

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

# fit model to example data
# See [example_truncated] for more details
est <- estimate_truncation(example_truncated,
  verbose = interactive(),
  chains = 2, iter = 2000
)

# summary of the distribution
est$dist
# summary of the estimated truncation cmf (can be applied to new data)
print(est$cmf)
# observations linked to truncation adjusted estimates
print(est$obs)
# validation plot of observations vs estimates
plot(est)

# Pass the truncation distribution to `epinow()`.
# Note, we're using the last snapshot as the observed data as it contains
# all the previous snapshots. Also, we're using the default options for
# illustrative purposes only.
out <- epinow(
  example_truncated[[5]],
  truncation = trunc_opts(est$dist)
)
plot(out)
options(old_opts)

Description

An example data frame of observed cases

Usage

example_confirmed

Format

A data frame containing cases reported on each date.

Description

An example of a generation time estimate. See here for details: https://github.com/epiforecasts/EpiNow2/blob/main/data-raw/generation-time.R

Usage

example_generation_time

Format

A dist_spec object summarising the distribution

Description

An example of an incubation period estimate. See here for details: https://github.com/epiforecasts/EpiNow2/blob/main/data-raw/incubation-period.R # nolint

Usage

example_incubation_period

Format

A dist_spec object summarising the distribution

Description

An example of an reporting delay estimate. See here for details: https://github.com/epiforecasts/EpiNow2/blob/main/data-raw/reporting-delay # nolint

Usage

example_reporting_delay

Format

A dist_spec object summarising the distribution

Description

An example dataset of observed cases with truncation applied. This data is generated internally for use in the example of estimate_truncation(). For details on how the data is generated, see https://github.com/epiforecasts/EpiNow2/blob/main/data-raw/truncated.R #nolint

Usage

example_truncated

Format

A list of data.tables containing cases reported on each date until a point of truncation. Each element of the list is a data.table with the following columns:

date

Date of case report.

confirm

Number of confirmed cases.

Description

his function exposes internal stan functions in R from a user supplied list of target files. Allows for testing of stan functions in R and potentially user use in R code.

Usage

expose_stan_fns(files, target_dir, ...)

Arguments

Value

No return value, called for side effects

Description

Helper function to extract the credible intervals present in a ⁠<data.frame>⁠.

Usage

extract_CrIs(summarised)

Arguments

Value

A numeric vector of credible intervals detected in the ⁠<data.frame>⁠.

Examples

samples <- data.frame(value = 1:10, type = "car")
summarised <- calc_CrIs(samples,
  summarise_by = "type",
  CrIs = c(seq(0.05, 0.95, 0.05))
)
extract_CrIs(summarised)

Description

Extracts posterior samples to use to initialise a full model fit. This may be useful for certain data sets where the sampler gets stuck or cannot easily be initialised. In estimate_infections(), epinow() and regional_epinow() this option can be engaged by setting ⁠stan_opts(init_fit = <stanfit>)⁠.

This implementation is based on the approach taken in epidemia authored by James Scott.

Usage

extract_inits(fit, current_inits, exclude_list = NULL, samples = 50)

Arguments

Value

A function that when called returns a set of initial conditions as a named list.

Description

If the object argument is a ⁠<stanfit>⁠ object, it simply returns the result of rstan::extract(). If it is a ⁠<CmdStanMCMC>⁠ it returns samples in the same format as rstan::extract() does for ⁠<stanfit>⁠ objects.

Usage

extract_samples(stan_fit, pars = NULL, include = TRUE)

Arguments

Value

List of data.tables with samples

Description

Extracts summarised parameter posteriors from a stanfit object using rstan::summary() in a format consistent with other summary functions in {EpiNow2}.

Usage

extract_stan_param(
  fit,
  params = NULL,
  CrIs = c(0.2, 0.5, 0.9),
  var_names = FALSE
)

Arguments

Value

A ⁠<data.table>⁠ summarising parameter posteriors. Contains a following variables: variable, mean, mean_se, sd, median, and lower_, upper_ followed by credible interval labels indicating the credible intervals present.

Description

A helper function that allows the selection of region specific settings if present and otherwise applies the overarching settings.

Usage

filter_opts(opts, region)

Arguments

Value

A list of options

Description

If the given ⁠<dist_spec>⁠ has any uncertainty, it is removed and the corresponding distribution converted into a fixed one.

Usage

## S3 method for class 'dist_spec'
fix_parameters(x, strategy = c("mean", "sample"), ...)

Arguments

Value

A ⁠<dist_spec>⁠ object without uncertainty

Examples

# An uncertain gamma distribution with mean 3 and sd 2
dist <- LogNormal(
  meanlog = Normal(3, 0.5), sdlog = Normal(2, 0.5), max = 20
)

fix_parameters(dist)

Description

This function simulates infections using an existing fit to observed cases but with a modified time-varying reproduction number. This can be used to explore forecast models or past counterfactuals. Simulations can be run in parallel using future::plan().

Usage

forecast_infections(
  estimates,
  R = NULL,
  model = NULL,
  samples = NULL,
  batch_size = 10,
  backend = "rstan",
  verbose = interactive()
)

Arguments

Value

A list of output as returned by estimate_infections() but based on results from the specified scenario rather than fitting.

See Also

dist_spec() generation_time_opts() delay_opts() rt_opts() estimate_infections() trunc_opts() stan_opts() obs_opts() gp_opts()

Examples

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

# get example case counts
reported_cases <- example_confirmed[1:50]

# fit model to data to recover Rt estimates
est <- estimate_infections(reported_cases,
  generation_time = generation_time_opts(example_generation_time),
  delays = delay_opts(example_incubation_period + example_reporting_delay),
  rt = rt_opts(prior = list(mean = 2, sd = 0.1), rw = 7),
  obs = obs_opts(scale = list(mean = 0.1, sd = 0.01)),
  gp = NULL, horizon = 0
)

# update Rt trajectory and simulate new infections using it
R <- c(rep(NA_real_, 26), rep(0.5, 10), rep(0.8, 14))
sims <- forecast_infections(est, R)
plot(sims)

# with a data.frame input of samples
R_dt <- data.frame(
  date = seq(
    min(summary(est, type = "parameters", param = "R")$date),
    by = "day", length.out = length(R)
  ),
  value = R
)
sims <- forecast_infections(est, R_dt)
plot(sims)

#' # with a data.frame input of samples
R_samples <- summary(est, type = "samples", param = "R")
R_samples <- R_samples[,
 .(date, sample, value)][sample <= 1000][date <= "2020-04-10"
]
R_samples <- R_samples[date >= "2020-04-01", value := 1.1]
sims <- forecast_infections(est, R_samples)
plot(sims)

options(old_opts)

Description

This function forecasts secondary observations using the output of estimate_secondary() and either observed primary data or a forecast of primary observations. See the examples of estimate_secondary() for one use case. It can also be combined with estimate_infections() to produce a forecast for a secondary observation from a forecast of a primary observation. See the examples of estimate_secondary() for example use cases on synthetic data. See here for an example of forecasting Covid-19 deaths from Covid-19 cases.

Usage

forecast_secondary(
  estimate,
  primary,
  primary_variable = "reported_cases",
  model = NULL,
  backend = "rstan",
  samples = NULL,
  all_dates = FALSE,
  CrIs = c(0.2, 0.5, 0.9)
)

Arguments

Value

A list containing: predictions (a ⁠<data.frame>⁠ ordered by date with the primary, and secondary observations, and a summary of the forecast secondary observations. For primary observations in the forecast horizon when uncertainty is present the median is used), samples a ⁠<data.frame>⁠ of forecast secondary observation posterior samples, and forecast a summary of the forecast secondary observation posterior.

See Also

estimate_secondary()

Description

Generation time estimates. See here for details: https://github.com/epiforecasts/EpiNow2/blob/main/data-raw/generation-time.R

Usage

generation_times

Format

A data.table of summarising the distribution

Description

Usage

get_distribution(x, id = NULL)

Arguments

Value

A character string naming the distribution (or "nonparametric")

Examples

dist <- Gamma(shape = 3, rate = 2, max = 10)
get_distribution(dist)

Description

Usage

get_parameters(x, id = NULL)

Arguments

Value

A list of parameters of the distribution.

Examples

dist <- Gamma(shape = 3, rate = 2)
get_parameters(dist)

Description

Usage

get_pmf(x, id = NULL)

Arguments

Value

The pmf of the distribution

Examples

dist <- discretise(Gamma(shape = 3, rate = 2, max = 10))
get_pmf(dist)

Description

Summarises results across regions either from input or from disk. See the examples for details.

Usage

get_regional_results(
  regional_output,
  results_dir,
  date,
  samples = TRUE,
  forecast = FALSE
)

Arguments

Value

A list of estimates, forecasts and estimated cases by date of report.

Examples

# get example multiregion estimates
regional_out <- readRDS(system.file(
    package = "EpiNow2", "extdata", "example_regional_epinow.rds"
))

# from output
results <- get_regional_results(regional_out$regional, samples = FALSE)

Description

Defines a list specifying the structure of the approximate Gaussian process. Custom settings can be supplied which override the defaults.

Usage

gp_opts(
  basis_prop = 0.2,
  boundary_scale = 1.5,
  ls_mean = 21,
  ls_sd = 7,
  ls_min = 0,
  ls_max = 60,
  alpha_mean = 0,
  alpha_sd = 0.05,
  kernel = c("matern", "se", "ou", "periodic"),
  matern_order = 3/2,
  matern_type,
  w0 = 1
)

Arguments

Value

A ⁠<gp_opts>⁠ object of settings defining the Gaussian process

Examples

# default settings
gp_opts()

# add a custom length scale
gp_opts(ls_mean = 4)

# use linear kernel
gp_opts(kernel = "periodic")

Description

See here # nolint for justification. Now handled internally by stan so may be removed in future updates if no user demand.

Usage

growth_to_R(r, gamma_mean, gamma_sd)

Arguments

Value

Numeric vector of reproduction number estimates

Examples

growth_to_R(0.2, 4, 1)

Description

Returns generation time parameters in a format for lower level model use.

Usage

gt_opts(
  dist = Fixed(1),
  ...,
  disease,
  source,
  max = 14,
  fixed = FALSE,
  default_cdf_cutoff = 0.001,
  weight_prior = TRUE
)

generation_time_opts(
  dist = Fixed(1),
  ...,
  disease,
  source,
  max = 14,
  fixed = FALSE,
  default_cdf_cutoff = 0.001,
  weight_prior = TRUE
)

Arguments

Details

Because the discretised renewal equation used in the package does not support zero generation times, any distribution specified here will be left-truncated at one, i.e. the first element of the nonparametric or discretised probability distribution used for the generation time is set to zero and the resulting distribution renormalised.

Value

A ⁠<generation_time_opts>⁠ object summarising the input delay distributions.

See Also

convert_to_logmean() convert_to_logsd() bootstrapped_dist_fit() Gamma() LogNormal() Fixed()

Examples

# default settings with a fixed generation time of 1
generation_time_opts()

# A fixed gamma distributed generation time
generation_time_opts(Gamma(mean = 3, sd = 2, max = 14))

# An uncertain gamma distributed generation time
generation_time_opts(
  Gamma(
    mean = Normal(mean = 3, sd = 1),
    sd = Normal(mean = 2, sd = 0.5),
    max = 14
  )
)

# An example generation time
gt_opts(example_generation_time)

Description

Incubation period estimates. See here for details: https://github.com/epiforecasts/EpiNow2/blob/main/data-raw/incubation-period.R # nolint

Usage

incubation_periods

Format

A data.table of summarising the distribution

Description

Usage

## S3 method for class 'dist_spec'
is_constrained(x, ...)

Arguments

Value

Logical; TRUE if x is constrained

Examples

# A fixed gamma distribution with mean 5 and sd 1.
dist1 <- Gamma(mean = 5, sd = 1, max = 20)

# An uncertain lognormal distribution with mean 3 and sd 2
dist2 <- LogNormal(mean = Normal(3, 0.5), sd = Normal(2, 0.5), max = 20)

# both distributions are constrained and therefore so is the sum
is_constrained(dist1 + dist2)

Description

Combines a list of values into formatted credible intervals.

Usage

make_conf(value, CrI = 90, reverse = FALSE)

Arguments

Value

A character vector formatted for reporting

Examples

value <- list(median = 2, lower_90 = 1, upper_90 = 3)
make_conf(value)

Description

Categorises a numeric variable into "Increasing" (< 0.05), "Likely increasing" (<0.4), "Stable" (< 0.6), "Likely decreasing" (< 0.95), "Decreasing" (<= 1)

Usage

map_prob_change(var)

Arguments

Value

A character variable.

Examples

var <- seq(0.01, 1, 0.01)
var

map_prob_change(var)

Description

This works out the maximum of all the (parametric / nonparametric) delay distributions combined in the passed <dist_spec> (ignoring any uncertainty in parameters)

Usage

## S3 method for class 'dist_spec'
max(x, ...)

Arguments

Value

A vector of means.

Examples

# A fixed gamma distribution with mean 5 and sd 1.
dist1 <- Gamma(mean = 5, sd = 1, max = 20)
max(dist1)

# An uncertain lognormal distribution with mean 3 and sd 2
dist2 <- LogNormal(mean = Normal(3, 0.5), sd = Normal(2, 0.5), max = 20)
max(dist2)

# The max the sum of two distributions
max(dist1 + dist2)

Description

This works out the mean of all the (parametric / nonparametric) delay distributions combined in the passed <dist_spec>.

Usage

## S3 method for class 'dist_spec'
mean(x, ..., ignore_uncertainty = FALSE)

Arguments

Examples

# A fixed lognormal distribution with mean 5 and sd 1.
dist1 <- LogNormal(mean = 5, sd = 1, max = 20)
mean(dist1)

# An uncertain gamma distribution with mean 3 and sd 2
dist2 <- Gamma(
 mean = Normal(3, 0.5), sd = Normal(2, 0.5), max = 20
)
mean(dist2)

# The mean of the sum of two distributions
mean(dist1 + dist2)

Description

This will convert all parameters to natural parameters before generating a dist_spec. If they have uncertainty this will be done using sampling.

Usage

new_dist_spec(params, distribution, max = Inf, cdf_cutoff = 0)

Arguments

Value

A dist_spec of the given specification.

Examples

new_dist_spec(
  params = list(mean = 2, sd = 1),
  distribution = "normal"
)

Description

Defines a list specifying the structure of the observation model. Custom settings can be supplied which override the defaults.

Usage

obs_opts(
  family = c("negbin", "poisson"),
  phi = list(mean = 0, sd = 0.25),
  weight = 1,
  week_effect = TRUE,
  week_length = 7,
  scale = 1,
  na = c("missing", "accumulate"),
  likelihood = TRUE,
  return_likelihood = FALSE
)

Arguments

Value

An ⁠<obs_opts>⁠ object of observation model settings.

Examples

# default settings
obs_opts()

# Turn off day of the week effect
obs_opts(week_effect = TRUE)

# Scale reported data
obs_opts(scale = list(mean = 0.2, sd = 0.02))

Description

Define a list of ⁠_opts()⁠ to pass to regional_epinow() ⁠_opts()⁠ accepting arguments. This is useful when different settings are needed between regions within a single regional_epinow() call. Using opts_list() the defaults can be applied to all regions present with an override passed to regions as necessary (either within opts_list() or externally).

Usage

opts_list(opts, reported_cases, ...)

Arguments

Value

A named list of options per region which can be passed to the ⁠_opt⁠ accepting arguments of regional_epinow.

See Also

regional_epinow() rt_opts()

Examples

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

# default settings
opts_list(rt_opts(), cases)

# add a weekly random walk in realland
opts_list(rt_opts(), cases, realland = rt_opts(rw = 7))

# add a weekly random walk externally
rt <- opts_list(rt_opts(), cases)
rt$realland$rw <- 7
rt

Description

Adds lineranges for user specified credible intervals

Usage

plot_CrIs(plot, CrIs, alpha, linewidth)

Arguments

Value

A {ggplot2} plot.

Description

Allows users to plot the output from estimate_infections() easily. In future releases it may be depreciated in favour of increasing the functionality of the S3 plot methods.

Usage

plot_estimates(
  estimate,
  reported,
  ylab,
  hline,
  obs_as_col = TRUE,
  max_plot = 10,
  estimate_type = c("Estimate", "Estimate based on partial data", "Forecast")
)

Arguments

Value

A ggplot2 object

Examples

# get example model results
out <- readRDS(system.file(
    package = "EpiNow2", "extdata", "example_estimate_infections.rds"
))

# plot infections
plot_estimates(
  estimate = out$summarised[variable == "infections"],
  reported = out$observations,
  ylab = "Cases", max_plot = 2
) + ggplot2::facet_wrap(~type, scales = "free_y")

# plot reported cases estimated via Rt
plot_estimates(
  estimate = out$summarised[variable == "reported_cases"],
  reported = out$observations,
  ylab = "Cases"
)

# plot Rt estimates
plot_estimates(
  estimate = out$summarised[variable == "R"],
  ylab = "Effective Reproduction No.",
  hline = 1
)

#' # plot Rt estimates without forecasts
plot_estimates(
  estimate = out$summarised[variable == "R"],
  ylab = "Effective Reproduction No.",
  hline = 1, estimate_type = "Estimate"
)

Description

Used to return a summary plot across regions (using results generated by summarise_results()).

May be depreciated in later releases in favour of enhanced S3 methods.

Usage

plot_summary(summary_results, x_lab = "Region", log_cases = FALSE, max_cases)

Arguments

Value

A {ggplot2} object

Description

This function takes a ⁠<dist_spec>⁠ object and plots its probability mass function (PMF) and cumulative distribution function (CDF) using {ggplot2}.

Usage

## S3 method for class 'dist_spec'
plot(x, samples = 50L, res = 1, cumulative = TRUE, ...)

Arguments

Examples

# A fixed lognormal distribution with mean 5 and sd 1.
dist1 <- LogNormal(mean = 1.6, sd = 0.5, max = 20)
# Plot discretised distribution with 1 day discretisation window
plot(dist1)
# Plot discretised distribution with 0.01 day discretisation window
plot(dist1, res = 0.01, cumulative = FALSE)

# An uncertain gamma distribution with mean 3 and sd 2
dist2 <- Gamma(
  mean = Normal(3, 0.5), sd = Normal(2, 0.5), max = 20
)
plot(dist2)

# Multiple distributions with 0.1 discretisation window and do not plot the
# cumulative distribution
plot(dist1 + dist2, res = 0.1, cumulative = FALSE)

Description

plot method for class ⁠<epinow>⁠.

Usage

## S3 method for class 'epinow'
plot(x, type = "summary", ...)

Arguments

Value

List of plots as produced by report_plots()

See Also

plot plot.estimate_infections report_plots estimate_infections

Description

plot method for class ⁠<estimate_infections>⁠.

Usage

## S3 method for class 'estimate_infections'
plot(
  x,
  type = c("summary", "infections", "reports", "R", "growth_rate", "all"),
  ...
)

Arguments

Value

List of plots as produced by report_plots()

See Also

plot report_plots estimate_infections

Description

plot method for class "estimate_secondary".

Usage

## S3 method for class 'estimate_secondary'
plot(x, primary = FALSE, from = NULL, to = NULL, new_obs = NULL, ...)

Arguments

Value

A ggplot object.

See Also

plot estimate_secondary

Description

plot() method for class ⁠<estimate_truncation>⁠. Returns a plot faceted over each dataset used in fitting with the latest observations as columns, the data observed at the time (and so truncated) as dots and the truncation adjusted estimates as a ribbon.

Usage

## S3 method for class 'estimate_truncation'
plot(x, ...)

Arguments

Value

ggplot2 object

See Also

plot estimate_truncation

Description

This displays the parameters of the uncertain and probability mass functions of fixed delay distributions combined in the passed <dist_spec>.

Usage

## S3 method for class 'dist_spec'
print(x, ...)

Arguments

Value

invisible

Examples

#' # A fixed lognormal distribution with mean 5 and sd 1.
dist1 <- LogNormal(mean = 1.5, sd = 0.5, max = 20)
print(dist1)

# An uncertain gamma distribution with mean 3 and sd 2
dist2 <- Gamma(
  mean = Normal(3, 0.5), sd = Normal(2, 0.5), max = 20
)
print(dist2)

Description

See here # nolint for justification. Now handled internally by stan so may be removed in future updates if no user demand.

Usage

R_to_growth(R, gamma_mean, gamma_sd)

Arguments

Value

Numeric vector of reproduction number estimates

Examples

R_to_growth(2.18, 4, 1)

Description

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(),
  stan = stan_opts(),
  horizon = 7,
  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),
  ...,
  reported_cases
)

Arguments

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

# 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 = list(mean = 2, sd = 0.2)),
  stan = stan_opts(
    samples = 100, warmup = 200
  ),
  verbose = interactive()
)
options(old_opts)

Description

Used to produce summary output either internally in regional_epinow or externally.

Usage

regional_summary(
  regional_output = NULL,
  data,
  results_dir = NULL,
  summary_dir = NULL,
  target_date = NULL,
  region_scale = "Region",
  all_regions = TRUE,
  return_output = is.null(summary_dir),
  plot = TRUE,
  max_plot = 10,
  ...
)

Arguments

Value

A list of summary measures and plots

See Also

regional_epinow

Examples

# get example output from regional_epinow model
regional_out <- readRDS(system.file(
    package = "EpiNow2", "extdata", "example_regional_epinow.rds"
))

regional_summary(
  regional_output = regional_out$regional,
  data = regional_out$summary$reported_cases
)

Description

Returns key summary plots for estimates. May be depreciated in later releases as current S3 methods are enhanced.

Usage

report_plots(summarised_estimates, reported, target_folder = NULL, ...)

Arguments

Value

A named list of ggplot2 objects, list(infections, reports, R, growth_rate, summary), which correspond to a summary combination (last item) and for the leading items.

See Also

plot_estimates() of summarised_estimates[variable == "infections"], summarised_estimates[variable == "reported_cases"], summarised_estimates[variable == "R"], and summarised_estimates[variable == "growth_rate"], respectively.

Examples

# get example output form estimate_infections
out <- readRDS(system.file(
    package = "EpiNow2", "extdata", "example_estimate_infections.rds"
))

# plot infections
plots <- report_plots(
  summarised_estimates = out$summarised,
  reported = out$observations
)
plots

Description

Creates a snapshot summary of estimates. May be removed in later releases as S3 methods are enhanced.

Usage

report_summary(
  summarised_estimates,
  rt_samples,
  target_folder = NULL,
  return_numeric = FALSE
)

Arguments

Value

A data.table containing formatted and numeric summary measures

Description

Deprecated; specify options in stan_opts() instead.

Usage

rstan_opts(object = NULL, samples = 2000, method = c("sampling", "vb"), ...)

Arguments

Value

A list of arguments to pass to the appropriate rstan functions.

See Also

rstan_sampling_opts() rstan_vb_opts()

Description

Deprecated; use stan_sampling_opts() instead.

Usage

rstan_sampling_opts(
  cores = getOption("mc.cores", 1L),
  warmup = 250,
  samples = 2000,
  chains = 4,
  control = list(),
  save_warmup = FALSE,
  seed = as.integer(runif(1, 1, 1e+08)),
  future = FALSE,
  max_execution_time = Inf,
  ...
)

Arguments

Value

A list of arguments to pass to rstan::sampling().

Description

Deprecated; use stan_vb_opts() instead.

Usage

rstan_vb_opts(samples = 2000, trials = 10, iter = 10000, ...)

Arguments

Value

A list of arguments to pass to rstan::vb().

Description

Defines a list specifying the optional arguments for the time-varying reproduction number. Custom settings can be supplied which override the defaults.

Usage

rt_opts(
  prior = list(mean = 1, sd = 1),
  use_rt = TRUE,
  rw = 0,
  use_breakpoints = TRUE,
  future = "latest",
  gp_on = c("R_t-1", "R0"),
  pop = 0
)

Arguments

Value

An ⁠<rt_opts>⁠ object with settings defining the time-varying reproduction number.

Examples

# default settings
rt_opts()

# add a custom length scale
rt_opts(prior = list(mean = 2, sd = 1))

# add a weekly random walk
rt_opts(rw = 7)

Description

Internal function that handles calling epinow(). Future work will extend this function to better handle stan logs and allow the user to modify settings between regions.

Usage

run_region(
  target_region,
  generation_time,
  delays,
  truncation,
  rt,
  backcalc,
  gp,
  obs,
  stan,
  horizon,
  CrIs,
  data,
  target_folder,
  target_date,
  return_output,
  output,
  complete_logger,
  verbose,
  progress_fn = NULL,
  ...
)

Arguments

Value

A list of processed output as produced by process_region()

See Also

regional_epinow()

Description

Returns a list of options defining the secondary model used in estimate_secondary(). This model is a combination of a convolution of previously observed primary reports combined with current primary reports (either additive or subtractive). It can optionally be cumulative. See the documentation of type for sensible options to cover most use cases and the returned values of secondary_opts() for all currently supported options.

Usage

secondary_opts(type = c("incidence", "prevalence"), ...)

Arguments

Value

A ⁠<secondary_opts>⁠ object of binary options summarising secondary model used in estimate_secondary(). Options returned are cumulative (should the secondary report be cumulative), historic (should a convolution of primary reported cases be used to predict secondary reported cases), primary_hist_additive (should the historic convolution of primary reported cases be additive or subtractive), current (should currently observed primary reported cases contribute to current secondary reported cases), primary_current_additive (should current primary reported cases be additive or subtractive).

See Also

estimate_secondary()

Examples

# incidence model
secondary_opts("incidence")

# prevalence model
secondary_opts("prevalence")

Description

Sets up default logging. Usage of logging is currently being explored as the current setup cannot log stan errors or progress.

Usage

setup_default_logging(
  logs = tempdir(check = TRUE),
  mirror_epinow = FALSE,
  target_date = NULL
)

Arguments

Value

No return value, called for side effects

Examples

setup_default_logging()

Description

A utility function that aims to streamline the set up of the required future backend with sensible defaults for most users of regional_epinow(). More advanced users are recommended to setup their own {future} backend based on their available resources. Running this requires the {future} package to be installed.

Usage

setup_future(
  data,
  strategies = c("multisession", "multisession"),
  min_cores_per_worker = 4
)

Arguments

Value

Numeric number of cores to use per worker. If greater than 1 pass to stan_args = list(cores = "output from setup future") or use future = TRUE. If only a single strategy is used then nothing is returned.

Description

Sets up {futile.logger} logging, which is integrated into {EpiNow2}. See the documentation for {futile.logger} for full details. By default {EpiNow2} prints all logs at the "INFO" level and returns them to the console. Usage of logging is currently being explored as the current setup cannot log stan errors or progress.

Usage

setup_logging(
  threshold = "INFO",
  file = NULL,
  mirror_to_console = FALSE,
  name = "EpiNow2"
)

Arguments

Value

Nothing

Description

Simulations are done from given initial infections and, potentially time-varying, reproduction numbers. Delays and parameters of the observation model can be specified using the same options as in estimate_infections().

Usage

simulate_infections(
  estimates,
  R,
  initial_infections,
  day_of_week_effect = NULL,
  generation_time = generation_time_opts(),
  delays = delay_opts(),
  truncation = trunc_opts(),
  obs = obs_opts(),
  CrIs = c(0.2, 0.5, 0.9),
  backend = "rstan",
  seeding_time = NULL,
  pop = 0,
  ...
)

Arguments