Package 'EpiNow2'

Description

Creates a delay distribution as the sum of two other delay distributions.

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 shape and rate normally distributed
# as Normal(3, 0.5) and Normal(2, 0.5) respectively
dist2 <- Gamma(
  shape = Normal(3, 0.5),
  rate = Normal(2, 0.5),
  max = 20
)
dist1 + dist2

Description

Compares two delay distributions

Usage

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

## S3 method for class 'dist_spec'
e1 != e2

Arguments

Value

TRUE or FALSE

Examples

Fixed(1) == Normal(1, 0.5)

Description

Add breakpoints to certain dates in a data set.

Usage

add_breakpoints(data, dates = as.Date(character(0)))

Arguments

Value

A data.table with breakpoint set to 1 on each of the specified dates.

Examples

reported_cases <- add_breakpoints(example_confirmed, as.Date("2020-03-26"))

Description

This function aims to detect spurious zeroes by comparing the 7-day average of the case counts to a threshold. If the 7-day average is above the threshold, the zero case count is replaced with NA.

Usage

apply_zero_threshold(data, threshold = Inf, obs_column = "confirm")

Arguments

Value

A data.table with the zero threshold applied.

Description

Convert outputs of EpiNow2 fitting and forecasting functions to forecast_sample objects via scoringutils::as_forecast_sample() for evaluating predictive performance. Methods are provided for objects returned by epinow(), estimate_infections(), forecast_secondary(), and estimate_truncation().

These methods extract sample-level posterior predictions via get_predictions() with format = "sample", merge them with the supplied observations on date, and pass the result to scoringutils::as_forecast_sample().

scoringutils is an optional dependency; calling these methods without it installed gives an informative error.

Usage

## S3 method for class 'estimate_infections'
as_forecast_sample(data, observations, horizon = 0, ...)

## S3 method for class 'epinow'
as_forecast_sample(data, observations, horizon = 0, ...)

## S3 method for class 'forecast_secondary'
as_forecast_sample(data, observations, horizon = 0, ...)

## S3 method for class 'estimate_truncation'
as_forecast_sample(data, observations, horizon = -Inf, ...)

Arguments

Value

A forecast_sample object as returned by scoringutils::as_forecast_sample(). Rows for which observations does not provide a value on the corresponding date are dropped.

See Also

get_predictions() for the underlying sample extraction.

Examples

library(scoringutils)

# samples and calculation time have been reduced for this example
# for real analyses, use at least samples = 2000
fit <- estimate_infections(example_confirmed[1:40],
  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)
)

forecast_obj <- as_forecast_sample(fit, observations = example_confirmed)
score(forecast_obj)

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
# bootstraps and samples have been reduced for this example
# for real analyses, use more
delays <- rlnorm(500, log(5), 1)
out <- bootstrapped_dist_fit(delays,
  samples = 500, bootstraps = 2,
  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 shape and rate normally distributed
# as Normal(3, 0.5) and Normal(2, 0.5) respectively
dist2 <- Gamma(
  shape = Normal(3, 0.5),
  rate = 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 meanlog and sdlog normally
# distributed as Normal(3, 0.5) and Normal(2, 0.5) respectively
dist2 <- LogNormal(
  meanlog = Normal(3, 0.5),
  sdlog = Normal(2, 0.5),
  max = 20
)

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

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), 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 vignette("delays") for background on delay distributions

Examples

# no delays
delay_opts()

# A single delay that has uncertainty
delay <- LogNormal(
  meanlog = Normal(1, 0.2),
  sdlog = 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

Discretise a <dist_spec>

Usage

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

discretize(x, ...)

Arguments

Value

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

Methodological details

The probability mass function is computed using the {primarycensored} package, which provides double censored PMF calculations. This correctly represents the probability mass function of a double censored distribution arising from the difference of two censored events.

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.

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 Abbott S., et al., "primarycensored: Primary Event Censored Distributions", 2025. doi:10.5281/zenodo.13632839

Examples

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

# An uncertain lognormal distribution with meanlog and sdlog normally
# distributed as Normal(3, 0.5) and Normal(2, 0.5) respectively
dist2 <- LogNormal(
  meanlog = Normal(3, 0.5),
  sdlog = 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

Constructors for the probability distributions supported by EpiNow2 as dist_spec objects.

Usage

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

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

Normal(mean, sd, ...)

Exp(rate, mean, ...)

Weibull(shape, scale, mean, sd, ...)

NonParametric(pmf, ...)

Fixed(value, ...)

Dirichlet(alpha, prior, concentration, ...)

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), nonparametric, and estimated nonparametric. The nonparametric is a special case where the probability mass function is given directly as a numeric vector. The estimated nonparametric allows the PMF to be estimated during model fitting using a Dirichlet prior.

Value

A dist_spec representing a distribution of the given specification.

See Also

vignette("delays") for an overview of how delay distributions are used in EpiNow2

Examples

LogNormal(mean = 4, sd = 1)
LogNormal(mean = 4, sd = 1, max = 10)
# If specifying uncertain parameters, use the natural parameters
LogNormal(meanlog = Normal(1.5, 0.5), sdlog = 0.25, max = 10)
Gamma(mean = 4, sd = 1)
Gamma(shape = 16, rate = 4)
Gamma(shape = Normal(16, 2), rate = Normal(4, 1))
Normal(mean = 4, sd = 1)
Normal(mean = 4, sd = 1, max = 10)
Exp(rate = 1)
Exp(mean = 4)
Weibull(shape = 1, scale = 1)
Weibull(shape = 1, scale = 1, max = 10)
Weibull(mean = 4, sd = 1)
NonParametric(c(0.1, 0.3, 0.2, 0.4))
NonParametric(c(0.1, 0.3, 0.2, 0.1, 0.1))

# With a Dirichlet prior
NonParametric(pmf = Dirichlet(c(1, 1, 1, 1)))
Fixed(value = 3)
Fixed(value = 3.5)
Dirichlet(c(1, 1, 1, 1))
Dirichlet(prior = c(0.1, 0.3, 0.4, 0.2), concentration = 10)

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(),
  forecast = forecast_opts(),
  stan = stan_opts(),
  CrIs = c(0.2, 0.5, 0.9),
  return_output = is.null(target_folder),
  output = c("samples", "plots", "latest", "fit", "timing", "estimate_infections"),
  plot_args = list(),
  target_folder = NULL,
  target_date,
  logs = tempdir(),
  id = "epinow",
  verbose = interactive()
)

Arguments

Value

An ⁠<epinow>⁠ object (inheriting from ⁠<estimate_infections>⁠) containing:

• fit: The stan fit object.

• args: A list of arguments used for fitting (stan data).

• observations: The input data (⁠<data.frame>⁠).

• timing: The run time (if output includes "timing").

See Also

get_samples() get_predictions() get_parameters() 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
# samples and calculation time have been reduced for this example
# for real analyses, use at least samples = 2000
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),
  stan = stan_opts(samples = 100, warmup = 200)
)
# 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.

This function is deprecated. Please use estimate_dist() instead, which provides better handling of censoring and truncation.

Usage

estimate_delay(delays, ...)

Arguments

Value

A ⁠<dist_spec>⁠ summarising the bootstrapped distribution

See Also

estimate_dist() for the recommended replacement

Examples

delays <- rlnorm(500, log(5), 1)
# Old way (deprecated):
# estimate_delay(delays, samples = 1000, bootstraps = 10)

# New way: see ?estimate_dist and
# vignette("estimate_dist_workflow") for date-based usage

Description

Fit a delay distribution accounting for primary and secondary event censoring (double interval censoring) and right truncation. Estimation is done via MCMC using a Stan model that vendors likelihood functions from the primarycensored package. For more flexible delay distribution modelling (e.g. time-varying delays, partial pooling, or regression on covariates), see the epidist package. If you use this function, please cite primarycensored in addition to EpiNow2.

Usage

estimate_dist(
  data,
  dist = "lognormal",
  priors = switch(dist, lognormal = list(meanlog = Normal(1, 1), sdlog = Normal(0.5,
    0.5)), gamma = list(shape = Normal(2, 2), rate = Normal(0.5, 0.5)), normal =
    list(mean = Normal(5, 5), sd = Normal(1, 1)), exp = list(rate = Normal(0.5, 0.5)),
    weibull = list(shape = Normal(2, 2), scale = Normal(5, 5))),
  primary = "uniform",
  primary_params = numeric(0),
  stan = stan_opts(),
  max_value = NULL,
  obs_time_threshold = 2,
  verbose = FALSE
)

Arguments

Details

The model fits an interval-censored delay distribution while accounting for:

• Primary event censoring (e.g., daily reporting of exposure)

• Secondary event censoring (e.g., daily reporting of symptom onset)

• Right truncation (observation window effects)

• Per-observation truncation times (via obs_date)

When a data frame with date columns is provided, observations are aggregated by unique combinations of ⁠(delay_lwr, delay_upr, pwindow, relative_obs_time)⁠ to reduce the number of likelihood evaluations. Observations where the relative observation time is much larger than the maximum observed delay are treated as untruncated (observation time set to infinity).

The primarycensored Stan functions are vendored (included in the package), so the model is pre-compiled and runs without needing primarycensored at runtime.

Limitations

• Delay distributions are limited to lognormal, gamma, normal, exponential, and weibull.

• The primary event distribution is limited to uniform or exponential growth with a fixed rate. Primary event parameters are not estimated.

• Left truncation is not yet exposed (internally set to 0).

Value

An ⁠<estimate_dist>⁠ object (inheriting from ⁠<epinowfit>⁠) with components:

fit

The Stan fit object.

args

The Stan data list used for fitting.

data

The input data.

Use get_parameters() to extract the fitted ⁠<dist_spec>⁠.

References

Park SW, et al. (2024) "Estimating epidemiological delay distributions for infectious diseases." doi:10.1101/2024.01.12.24301247

Charniga K, Park SW, et al. (2024) "Best practices for estimating and reporting epidemiological delay distributions of infectious diseases." PLoS Comput Biol 20(10): e1012520. doi:10.1371/journal.pcbi.1012520

Please cite primarycensored if you use this function; see citation("primarycensored").

See Also

vignette("estimate_dist_workflow", package = "EpiNow2") for a worked example, and primarycensored::primarycensored-package for the underlying censoring methodology.

Examples

# Fit lognormal distribution from date-based linelist
if (requireNamespace("primarycensored", quietly = TRUE)) {
  set.seed(1)
  n <- 100
  D <- 30
  pdate_lwr <- as.Date("2023-01-01") + rpois(n, 5)
  delays_sim <- primarycensored::rprimarycensored(
    n = n, rdist = rlnorm,
    meanlog = log(5), sdlog = 0.5,
    pwindow = 1, D = D
  )
  linelist <- data.frame(
    pdate_lwr = pdate_lwr,
    sdate_lwr = pdate_lwr + delays_sim,
    obs_date = pdate_lwr + D
  )
  result <- estimate_dist(linelist, dist = "lognormal")
}

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(),
  forecast = forecast_opts(),
  stan = stan_opts(),
  id = "estimate_infections",
  verbose = interactive()
)

Arguments

Value

An ⁠<estimate_infections>⁠ object containing:

• fit: The stan fit object.

• args: A list of arguments used for fitting (stan data).

• observations: The input data (⁠<data.frame>⁠).

See Also

get_samples() get_predictions() get_parameters() 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:40]

# 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
# samples and calculation time have been reduced for this example
# for real analyses, use at least samples = 2000
def <- estimate_infections(reported_cases,
  generation_time = gt_opts(generation_time),
  delays = delay_opts(incubation_period + reporting_delay),
  rt = rt_opts(prior = LogNormal(mean = 2, sd = 0.1)),
  stan = stan_opts(samples = 100, warmup = 200)
)
# 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),
  priors = NULL,
  model = NULL,
  weigh_delay_priors = FALSE,
  verbose = interactive()
)

Arguments

Value

An ⁠<estimate_secondary>⁠ object containing:

• fit: The stan fit object.

• args: A list of arguments used for fitting (stan data).

• observations: The input data (⁠<data.frame>⁠).

See Also

get_samples() get_predictions() get_parameters()

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 = Normal(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 = Normal(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 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.

The model of truncation is as follows:

1. The truncation distribution can be any parametric family supported by dist_spec (e.g. log-normal, gamma), with parameters 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 using the selected observation model (negative binomial or Poisson) with an additive noise term to handle zero observations.

This can be thought of as a Bayesian form of the chain-ladder nowcasting approach in the baselinenowcast package. For settings requiring time-varying delays, see epinowcast.

Usage

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

Arguments

Value

An ⁠<estimate_truncation>⁠ object containing:

• observations: The input data (list of ⁠<data.frame>⁠s).

• args: A list of arguments used for fitting (stan data).

• fit: The stan fit object.

See Also

get_samples() get_predictions() get_parameters()

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
# iterations and calculation time have been reduced for this example
# for real analyses, use more
est <- estimate_truncation(example_truncated,
  verbose = interactive(),
  chains = 2, iter = 200
)

# extract the estimated truncation distribution
get_parameters(est)[["truncation"]]
# summarise the truncation distribution parameters
summary(est)
# 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(
  generation_time = generation_time_opts(example_generation_time),
  example_truncated[[5]],
  truncation = trunc_opts(get_parameters(est)[["truncation"]])
)
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

This function ensures that all days between the first and last date in the data are present. It adds an accumulate column that indicates whether modelled observations should be accumulated onto a later data point. point. This is useful for modelling data that is reported less frequently than daily, e.g. weekly incidence data, as well as other reporting artifacts such as delayed weekedn reporting. The function can also be used to fill in missing observations with zeros.

Usage

fill_missing(
  data,
  missing_dates = c("ignore", "accumulate", "zero"),
  missing_obs = c("ignore", "accumulate", "zero"),
  initial_accumulate,
  obs_column = "confirm",
  by = NULL
)

Arguments

Value

a data.table with an accumulate column that indicates whether values are accumulated (see the documentation of the data argument in estimate_infections())

Examples

cases <- data.table::copy(example_confirmed)
## calculate weekly sum
cases[, confirm := data.table::frollsum(confirm, 7)]
## limit to dates once a week
cases <- cases[seq(7, nrow(cases), 7)]
## set the second observation to missing
cases[2, confirm := NA]
## fill missing data
fill_missing(cases, missing_dates = "accumulate", initial_accumulate = 7)

Description

Filter leading zeros from a data set.

Usage

filter_leading_zeros(data, obs_column = "confirm", by = NULL)

Arguments

Value

A data.table with leading zeros removed.

Examples

cases <- data.frame(
  date = as.Date("2020-01-01") + 0:10,
  confirm = c(0, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9)
)
filter_leading_zeros(cases)

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 shape and rate normally distributed
# as Normal(3, 0.5) and Normal(2, 0.5) respectively
dist <- Gamma(
  shape = Normal(3, 0.5),
  rate = 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 ⁠<forecast_infections>⁠ object containing simulated infections and cases from the specified scenario. The structure is similar to estimate_infections() output but contains samples rather than fit.

See Also

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:40]

# fit model to data to recover Rt estimates
# samples and calculation time have been reduced for this example
# for real analyses, use at least samples = 2000
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 = LogNormal(mean = 2, sd = 0.1), rw = 7),
  obs = obs_opts(scale = Normal(mean = 0.1, sd = 0.01)),
  gp = NULL,
  forecast = forecast_opts(horizon = 0),
  stan = stan_opts(samples = 100, warmup = 200)
)

# update Rt trajectory and simulate new infections using it
# keeping the first 30 days' estimates and adding a 10-day forecast
R <- c(rep(NA_real_, 30), rep(0.8, 10))
sims <- forecast_infections(est, R)
plot(sims)

options(old_opts)

Description

Defines a list specifying the arguments passed to underlying stan backend functions via stan_sampling_opts() and stan_vb_opts(). Custom settings can be supplied which override the defaults.

Usage

forecast_opts(horizon = 7, accumulate)

Arguments

Value

A ⁠<forecast_opts>⁠ object of forecast setting.

See Also

fill_missing()

Examples

forecast_opts(horizon = 28, accumulate = 7)

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

Get the distribution of a ⁠<dist_spec>⁠

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

Generic function to extract parameters. For dist_spec objects, extracts the distribution parameters (e.g., shape and rate for Gamma). For fitted model objects, extracts estimated parameters and delays as dist_spec objects that can be used as priors.

Usage

get_parameters(x, ...)

## S3 method for class 'dist_spec'
get_parameters(x, id = NULL, ...)

## S3 method for class 'epinowfit'
get_parameters(x, ...)

## S3 method for class 'estimate_dist'
get_parameters(x, ...)

Arguments

Value

For dist_spec: a list of distribution parameters. For fitted models: a named list of dist_spec objects.

Examples

# For dist_spec objects
dist <- Gamma(shape = 3, rate = 2)
get_parameters(dist)

## Not run: 
# For fitted models - extract estimated distributions
dists <- get_parameters(fit)
names(dists)

## End(Not run)

Description

Get the probability mass function of a nonparametric distribution

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

Extracts predictions from a fitted model. For estimate_infections() returns predicted reported cases, for estimate_secondary() returns predicted secondary observations. For estimate_truncation() returns reconstructed observations adjusted for truncation.

Usage

get_predictions(object, ...)

## S3 method for class 'estimate_infections'
get_predictions(
  object,
  format = c("summary", "sample", "quantile"),
  CrIs = c(0.2, 0.5, 0.9),
  quantiles = c(0.05, 0.25, 0.5, 0.75, 0.95),
  ...
)

## S3 method for class 'estimate_secondary'
get_predictions(
  object,
  format = c("summary", "sample", "quantile"),
  CrIs = c(0.2, 0.5, 0.9),
  quantiles = c(0.05, 0.25, 0.5, 0.75, 0.95),
  ...
)

## S3 method for class 'forecast_infections'
get_predictions(
  object,
  format = c("summary", "sample", "quantile"),
  CrIs = c(0.2, 0.5, 0.9),
  quantiles = c(0.05, 0.25, 0.5, 0.75, 0.95),
  ...
)

## S3 method for class 'forecast_secondary'
get_predictions(
  object,
  format = c("summary", "sample", "quantile"),
  CrIs = c(0.2, 0.5, 0.9),
  quantiles = c(0.05, 0.25, 0.5, 0.75, 0.95),
  ...
)

## S3 method for class 'estimate_truncation'
get_predictions(
  object,
  format = c("summary", "sample", "quantile"),
  CrIs = c(0.2, 0.5, 0.9),
  quantiles = c(0.05, 0.25, 0.5, 0.75, 0.95),
  ...
)

Arguments

Value

A data.table with columns depending on format:

• format = "summary": date, mean, sd, median, and credible intervals

• format = "sample": forecast_date, date, horizon, sample, predicted

• format = "quantile": forecast_date, date, horizon, quantile_level, predicted

Examples

## Not run: 
# After fitting a model
# Get summary predictions (default)
predictions <- get_predictions(fit)

# Get sample-level predictions for scoringutils
samples <- get_predictions(fit, format = "sample")

# Get quantile predictions for scoringutils
quantiles <- get_predictions(fit, format = "quantile")

## End(Not run)

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

Extracts posterior samples from a fitted model, combining all parameters into a single data.table with dates and metadata.

Usage

get_samples(object, ...)

## S3 method for class 'estimate_infections'
get_samples(object, ...)

## S3 method for class 'epinow'
get_samples(object, ...)

## S3 method for class 'forecast_infections'
get_samples(object, ...)

## S3 method for class 'estimate_secondary'
get_samples(object, ...)

## S3 method for class 'forecast_secondary'
get_samples(object, ...)

## S3 method for class 'estimate_truncation'
get_samples(object, ...)

Arguments

Value

A data.table with columns: date, variable, strat, sample, time, value, type. Contains all posterior samples for all parameters.

Examples

## Not run: 
# After fitting a model
samples <- get_samples(fit)
# Filter to specific parameters
R_samples <- samples[variable == "R"]

## End(Not run)

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 = LogNormal(mean = 21, sd = 7, max = 60),
  alpha = Normal(mean = 0, sd = 0.01),
  kernel = c("matern", "se", "ou", "periodic"),
  matern_order = 3/2,
  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 = LogNormal(mean = 4, sd = 1, max = 20))

# 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), default_cdf_cutoff = 0.001, weight_prior = TRUE)

generation_time_opts(
  dist = Fixed(1),
  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(
    shape = Normal(mean = 3, sd = 1),
    rate = Normal(mean = 2, sd = 0.5),
    max = 14
  )
)

# An example generation time
gt_opts(example_generation_time)

Description

Check if a <dist_spec> is constrained, i.e. has a finite maximum or nonzero CDF cutoff.

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 meanlog and sdlog normally
# distributed as Normal(3, 0.5) and Normal(2, 0.5) respectively
dist2 <- LogNormal(
  meanlog = Normal(3, 0.5),
  sdlog = 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 meanlog and sdlog normally
# distributed as Normal(3, 0.5) and Normal(2, 0.5) respectively
dist2 <- LogNormal(
  meanlog = Normal(3, 0.5),
  sdlog = 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 shape and rate normally distributed
# as Normal(3, 0.5) and Normal(2, 0.5) respectively
dist2 <- Gamma(
  shape = Normal(3, 0.5),
  rate = 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"),
  dispersion = Normal(mean = 0, sd = 0.25),
  weight = 1,
  week_effect = TRUE,
  week_length = 7,
  scale = Fixed(1),
  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 = FALSE)

# Scale reported data
obs_opts(scale = Normal(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 credible intervals to a plot, either as ribbons or error bars.

Usage

plot_CrIs(plot, CrIs, alpha, linewidth, style = c("ribbon", "linerange"))

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"),
  style = c("ribbon", "linerange")
)

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 = summary(out, type = "parameters", param = "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 = summary(out, type = "parameters", param = "reported_cases"),
  reported = out$observations,
  ylab = "Cases"
)

# plot Rt estimates
plot_estimates(
  estimate = summary(out, type = "parameters", param = "R"),
  ylab = "Effective Reproduction No.",
  hline = 1
)

#' # plot Rt estimates without forecasts
plot_estimates(
  estimate = summary(out, type = "parameters", param = "R"),
  ylab = "Effective Reproduction No.",
  hline = 1, estimate_type = "Estimate"
)

# plot with error bars instead of ribbons
plot_estimates(
  estimate = summary(out, type = "parameters", param = "R"),
  ylab = "Effective Reproduction No.",
  hline = 1, style = "linerange"
)

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 shape and rate normally distributed
# as Normal(3, 0.5) and Normal(2, 0.5) respectively
dist2 <- Gamma(
  shape = Normal(3, 0.5),
  rate = 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 ⁠<estimate_infections>⁠.

Usage

## S3 method for class 'estimate_infections'
plot(x, type = "summary", CrIs = c(0.2, 0.5, 0.9), ...)

Arguments

Value

List of plots as produced by report_plots()

See Also

report_plots()

Examples

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

# plot with error bars instead of ribbons
plot(out, style = "linerange")

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

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

estimate_truncation()

Description

plot method for class ⁠<forecast_infections>⁠.

Usage

## S3 method for class 'forecast_infections'
plot(x, type = "summary", CrIs = c(0.2, 0.5, 0.9), ...)

Arguments

Value

List of plots as produced by report_plots()

See Also

report_plots() forecast_infections()

Description

Plot method for forecast secondary observations.

Usage

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

Arguments

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 shape and rate normally distributed
# as Normal(3, 0.5) and Normal(2, 0.5) respectively
dist2 <- Gamma(
  shape = Normal(3, 0.5), rate = Normal(2, 0.5), max = 20
)
print(dist2)

Description

Print information about an object that has resulted from a model fit.

Usage

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

Arguments

Value

Invisible

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(),
  forecast = forecast_opts(),
  stan = stan_opts(),
  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),
  ...
)