Type:	Package
Title:	Estimate and Forecast Real-Time Infection Dynamics
Version:	1.8.0
Description:	Estimates the time-varying reproduction number, rate of spread, and doubling time using a renewal equation approach combined with Bayesian inference via Stan. Supports Gaussian process and random walk priors for modelling changes in transmission over time. Accounts for delays between infection and observation (incubation period, reporting delays), right-truncation in recent data, day-of-week effects, and observation overdispersion. Can estimate relationships between primary and secondary outcomes (e.g., cases to hospitalisations or deaths) and forecast both. Runs across multiple regions in parallel. Based on Abbott et al. (2020) <doi:10.12688/wellcomeopenres.16006.1> and Gostic et al. (2020) <doi:10.1101/2020.06.18.20134858>.
License:	MIT + file LICENSE
URL:	https://epiforecasts.io/EpiNow2/, https://epiforecasts.io/EpiNow2/dev/, https://github.com/epiforecasts/EpiNow2
BugReports:	https://github.com/epiforecasts/EpiNow2/issues
Depends:	R (≥ 3.5.0)
Imports:	checkmate, cli, data.table (≥ 1.15.0), futile.logger (≥ 1.4), ggplot2, lifecycle, lubridate, methods, patchwork, posterior, primarycensored, purrr, R.utils (≥ 2.0.0), Rcpp (≥ 0.12.0), rlang (≥ 0.4.7), rstan (≥ 2.26.0), rstantools (≥ 2.2.0), runner, scales, stats, truncnorm, utils
Suggests:	cmdstanr, future, future.apply, knitr, parallelly, progressr, rmarkdown, scoringutils, spelling, testthat, withr
LinkingTo:	BH (≥ 1.66.0), Rcpp (≥ 0.12.0), RcppEigen (≥ 0.3.3.3.0), RcppParallel (≥ 5.0.1), rstan (≥ 2.26.0), StanHeaders (≥ 2.26.0)
Additional_repositories:	https://production.r-multiverse.org/2025-12-15
Biarch:	true
Config/testthat/edition:	3
Config/Needs/dev:	covr, here, hexSticker, lintr, magick, pkgdown, precommit, styler, usethis
Encoding:	UTF-8
Language:	en-GB
LazyData:	true
RoxygenNote:	7.3.3
SystemRequirements:	GNU make C++17
VignetteBuilder:	knitr
NeedsCompilation:	yes
Packaged:	2026-02-04 22:49:39 UTC; eidesfun
Author:	Sam Abbott [aut], Joel Hellewell [aut], Katharine Sherratt [aut], Katelyn Gostic [aut], Joe Hickson [aut], Hamada S. Badr [aut], Michael DeWitt [aut], James M. Azam [aut], Adrian Lison [aut], Robin Thompson [ctb], Sophie Meakin [ctb], James Munday [ctb], Nikos Bosse [ctb], Paul Mee [ctb], Peter Ellis [ctb], Pietro Monticone [ctb], Lloyd Chapman [ctb], Andrew Johnson [ctb], Kaitlyn Johnson [ctb], Adam Howes [ctb], Sebastian Funk [aut, cre]
Maintainer:	Sebastian Funk <sebastian.funk@lshtm.ac.uk>
Repository:	CRAN
Date/Publication:	2026-02-04 23:30:02 UTC

EpiNow2: Estimate and Forecast Real-Time Infection Dynamics

Description

Estimates the time-varying reproduction number, rate of spread, and doubling time using a renewal equation approach combined with Bayesian inference via Stan. Supports Gaussian process and random walk priors for modelling changes in transmission over time. Accounts for delays between infection and observation (incubation period, reporting delays), right-truncation in recent data, day-of-week effects, and observation overdispersion. Can estimate relationships between primary and secondary outcomes (e.g., cases to hospitalisations or deaths) and forecast both. Runs across multiple regions in parallel. Based on Abbott et al. (2020) doi:10.12688/wellcomeopenres.16006.1 and Gostic et al. (2020) doi:10.1101/2020.06.18.20134858.

Author(s)

Maintainer: Sebastian Funk sebastian.funk@lshtm.ac.uk (ORCID)

Authors:

• Sam Abbott sam.abbott@lshtm.ac.uk (ORCID)

• Joel Hellewell joel.hellewell@lshtm.ac.uk (ORCID)

• Katharine Sherratt katharine.sherratt@lshtm.ac.uk

• Katelyn Gostic kgostic@uchicago.edu

• Joe Hickson joseph.hickson@metoffice.gov.uk

• Hamada S. Badr badr@jhu.edu (ORCID)

• Michael DeWitt me.dewitt.jr@gmail.com (ORCID)

• James M. Azam james.azam@lshtm.ac.uk (ORCID)

• Adrian Lison adrian.lison@bsse.ethz.ch (ORCID)

Other contributors:

• Robin Thompson robin.thompson@lshtm.ac.uk [contributor]

• Sophie Meakin sophie.meakin@lshtm.ac.uk [contributor]

• James Munday james.munday@lshtm.ac.uk [contributor]

• Nikos Bosse [contributor]

• Paul Mee paul.mee@lshtm.ac.uk [contributor]

• Peter Ellis peter.ellis2013nz@gmail.com [contributor]

• Pietro Monticone pietro.monticone@edu.unito.it [contributor]

• Lloyd Chapman lloyd.chapman1@lshtm.ac.uk [contributor]

• Andrew Johnson andrew.johnson@arjohnsonau.com [contributor]

• Kaitlyn Johnson johnsonkaitlyne9@gmail.com (ORCID) [contributor]

• Adam Howes adamthowes@gmail.com (ORCID) [contributor]

See Also

Useful links:

• https://epiforecasts.io/EpiNow2/

• https://epiforecasts.io/EpiNow2/dev/

• https://github.com/epiforecasts/EpiNow2

• Report bugs at https://github.com/epiforecasts/EpiNow2/issues

Extract elements from epinow objects with deprecated warnings

Description

Provides backward compatibility for the old return structure. The previous structure with estimates, estimated_reported_cases, summary, plots, and estimate_infections elements is deprecated. Use the standard S3 methods instead:

• estimates$samples - use get_samples(object)

• estimates$summarised - use summary(object, type = "parameters")

• estimated_reported_cases - use estimates_by_report_date(object)

• summary - use summary(object)

• plots - use plot(object)

• estimate_infections - use the object directly (it now inherits from estimate_infections)

Usage

## S3 method for class 'epinow'
x$name

Arguments

Value

The requested element with a deprecation warning for deprecated elements

Extract elements from estimate_infections objects with deprecated warnings

Description

Provides backward compatibility for the old return structure. The previous structure with samples and summarised elements is deprecated. Use the accessor methods instead:

• samples - use get_samples(object)

• summarised - use summary(object, type = "parameters")

Usage

## S3 method for class 'estimate_infections'
x$name

Arguments

Value

The requested element with a deprecation warning for deprecated elements

Extract elements from estimate_secondary objects with deprecated warnings

Description

Provides backward compatibility for the old return structure. The previous structure with predictions, posterior, and data elements is deprecated. Use the accessor methods instead:

• predictions - use get_predictions(object)

• posterior - use get_samples(object)

• data - use object$observations

Usage

## S3 method for class 'estimate_secondary'
x$name

Arguments

Value

The requested element with a deprecation warning

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

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

Compares two delay distributions

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)

Probability distributions

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

Convert Reproduction Numbers to Growth Rates

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)

Extract elements from epinow objects with bracket notation

Description

Provides backward compatibility for bracket-based access to deprecated elements. See $.epinow for details on the deprecation.

Usage

## S3 method for class 'epinow'
x[[i]]

Arguments

Value

The requested element with a deprecation warning for deprecated elements

Extract elements from estimate_infections objects with bracket notation

Description

Provides backward compatibility for bracket-based access to deprecated elements. See $.estimate_infections for details on the deprecation.

Usage

## S3 method for class 'estimate_infections'
x[[i]]

Arguments

Value

The requested element with a deprecation warning for deprecated elements

Extract elements from estimate_secondary objects with bracket notation

Description

Provides backward compatibility for bracket-based access to deprecated elements. See $.estimate_secondary for details on the deprecation.

Usage

## S3 method for class 'estimate_secondary'
x[[i]]

Arguments

Value

The requested element with a deprecation warning for deprecated elements

Add breakpoints to certain dates in a data set.

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

Adds a day of the week vector

Description

Adds a day of the week vector

Usage

add_day_of_week(dates, week_effect = 7)

Arguments

Value

A numeric vector containing the period day of the week index

Examples

## Not run: 
dates <- seq(as.Date("2020-03-15"), by = "days", length.out = 15)
# Add date based day of week
add_day_of_week(dates, 7)

# Add shorter week
add_day_of_week(dates, 4)

## End(Not run)

Add missing values for future dates

Description

Add missing values for future dates

Usage

add_horizon(data, horizon, accumulate = 1L, obs_column = "confirm", by = NULL)

Arguments

Value

A data.table with missing values for future dates

Allocate Delays into Required Stan Format

Description

Allocate delays for stan. Used in delay_opts().

Usage

allocate_delays(delay_var, no_delays)

Arguments

Value

A numeric array

Allocate Empty Parameters to a List

Description

Allocate missing parameters to be empty two dimensional arrays. Used internally by forecast_infections().

Usage

allocate_empty(data, params, n = 0)

Arguments

Value

A list of parameters some allocated to be empty

Apply default CDF cutoff to a <dist_spec> if it is unconstrained

Description

Apply default CDF cutoff to a <dist_spec> if it is unconstrained

Usage

apply_default_cdf_cutoff(dist, default_cdf_cutoff, cdf_cutoff_set)

Arguments

Value

A <dist_spec> with the default CDF cutoff set if previously not constrained

Convert zero case counts to NA (missing) if the 7-day average is above a threshold.

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.

Back Calculation Options

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

Fit a Subsampled Bootstrap to Integer Values and Summarise Distribution Parameters

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

Define bounds of a ⁠<dist_spec>⁠

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

Combines multiple delay distributions for further processing

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)

Calculate Credible Interval

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

Calculate Credible Intervals

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

Calculate All Summary Measures

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

Calculate Summary Statistics

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

Validate probability distribution for using as generation time

Description

does all the checks incheck_stan_delay() and additionally makes sure that if dist is nonparametric, its first element is zero.

Usage

check_generation_time(dist)

Arguments

Value

Called for its side effects.

Validate data input

Description

check_reports_valid() checks that the supplied data is a ⁠<data.frame>⁠, and that it has the right column names and types. In particular, it checks that the date column is in date format and does not contain NAs, and that the other columns are numeric.

Usage

check_reports_valid(
  data,
  model = c("estimate_infections", "estimate_secondary")
)

Arguments

Value

Called for its side effects.

Check that PMF tail is not sparse

Description

Checks if the tail of a PMF vector has more than span consecutive values smaller than tol and throws a warning if so.

Usage

check_sparse_pmf_tail(pmf, span = 5, tol = 1e-06)

Arguments

Value

Called for its side effects.

Validate probability distribution for passing to stan

Description

check_stan_delay() checks that the supplied data is a ⁠<dist_spec>⁠, that it is a supported distribution, and that is has a finite maximum.

Usage

check_stan_delay(dist)

Arguments

Value

Called for its side effects.

Check and warn if truncation distribution is longer than observed time

Description

Checks if the truncation distribution PMF is longer than the observed time period (excluding seeding time and forecast horizon). The truncation is applied to the observed time period in the Stan model, so having a truncation distribution longer than this period means the tail of the distribution will be used.

Usage

check_truncation_length(stan_args, time_points)

Arguments

Value

Called for its side effects

Clean Nowcasts for a Supplied Date

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

Clean Regions

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

Collapse nonparametric distributions in a <dist_spec>

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

Combine time-varying and static parameters

Description

Internal helper that combines time-varying parameters (which get their variable name from list keys) with static parameters (which already have a variable column from extractors).

Usage

combine_tv_and_static_params(time_varying_list, raw_samples, args)

Arguments

Value

A data.table combining all parameters with variable column

Construct Output

Description

Combines the output produced internally by epinow into a single list.

Usage

construct_output(
  estimates,
  estimated_reported_cases,
  plots = NULL,
  summary = NULL,
  samples = TRUE,
  CrIs = c(0.2, 0.5, 0.9)
)

Arguments

Value

A list of output as returned by epinow

Convert mean and sd to log mean for a log normal distribution

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)

Convert mean and sd to log standard deviation for a log normal distribution

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)

Internal function for converting parameters to natural parameters.

Description

This is used for preprocessing before generating a dist_spec object from a given set of parameters and distribution

Usage

convert_to_natural(params, distribution)

Arguments

Value

A list with two elements, params_mean and params_sd, containing mean and sd of natural parameters.

Examples

## Not run: 
convert_to_natural(
  params = list(mean = 2, sd = 1),
  distribution = "gamma"
)

## End(Not run)

Convolve and scale a time series

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

Copy Results From Dated Folder to Latest

Description

Copies output from the dated folder to a latest folder. May be undergo changes in later releases.

Usage

copy_results_to_latest(target_folder = NULL, latest_folder = NULL)

Arguments

Value

No return value, called for side effects

Create Back Calculation Data

Description

Takes the output of backcalc_opts() and converts it into a list understood by stan.

Usage

create_backcalc_data(backcalc = backcalc_opts())

Arguments

Value

A list of settings defining the Gaussian process

See Also

backcalc_opts()

Create initial conditions for delays

Description

Create initial conditions for delays

Usage

create_delay_inits(stan_data)

Arguments

Value

A list of initial conditions for delays

Construct the Required Future Rt assumption

Description

Converts the future argument from rt_opts() into arguments that can be passed to stan.

Usage

create_future_rt(future = c("latest", "project", "estimate"), delay = 0)

Arguments

Value

A list containing a logical called fixed and an integer called from

Create Gaussian Process Data

Description

Takes the output of gp_opts() and converts it into a list understood by stan.

Usage

create_gp_data(gp = gp_opts(), data)

Arguments

Value

A list of settings defining the Gaussian process

See Also

gp_opts()

Examples

## Not run: 
# define input data required
data <- list(
  t = 30,
  seeding_time = 7,
  horizon = 7
)

# default gaussian process data
create_gp_data(data = data)

# settings when no gaussian process is desired
create_gp_data(NULL, data)

# custom lengthscale
create_gp_data(gp_opts(ls_mean = 14), data)

## End(Not run)

Create summary output from infection estimation objects

Description

This function creates summary output from infection estimation objects (either estimate_infections or forecast_infections). It is used internally by summary.estimate_infections() and summary.forecast_infections() to provide a consistent summary interface.

Usage

create_infection_summary(
  object,
  type = c("snapshot", "parameters"),
  target_date = NULL,
  params = NULL,
  CrIs = c(0.2, 0.5, 0.9),
  ...
)

Arguments

Value

A ⁠<data.frame>⁠ of summary output, either a snapshot summary (via report_summary()) or parameter summaries (via calc_summary_measures()).

See Also

summary.estimate_infections() summary.forecast_infections() report_summary() calc_summary_measures()

Create Initial Conditions Generating Function

Description

Uses the output of create_stan_data() to create a function which can be used to sample from the prior distributions (or as close as possible) for parameters. Used in order to initialise each stan chain within a range of plausible values.

Usage

create_initial_conditions(stan_data, params)

Arguments

Value

An initial condition generating function

Create Observation Model Settings

Description

Takes the output of obs_opts() and converts it into a list understood by stan.

Usage

create_obs_model(obs = obs_opts(), dates)

Arguments

Value

A list of settings ready to be passed to stan defining the Observation Model

See Also

obs_opts()

Examples

## Not run: 
dates <- seq(as.Date("2020-03-15"), by = "days", length.out = 15)
# default observation model data
create_obs_model(dates = dates)

# Poisson observation model
create_obs_model(obs_opts(family = "poisson"), dates = dates)

# Applying a observation scaling to the data
create_obs_model(
  obs_opts(scale = Normal(mean = 0.4, sd = 0.01)),
  dates = dates
)

# Apply a custom week week length
create_obs_model(obs_opts(week_length = 3), dates = dates)

## End(Not run)

Create Time-varying Reproduction Number Data

Description

Takes the output from rt_opts() and converts it into a list understood by stan.

Usage

create_rt_data(
  rt = rt_opts(),
  breakpoints = NULL,
  delay = 0,
  horizon = 0,
  data = NULL
)

Arguments

Value

A list of settings defining the time-varying reproduction number

See Also

rt_opts()

Examples

## Not run: 
# default Rt data
create_rt_data()

# settings when no Rt is desired
create_rt_data(rt = NULL)

# using breakpoints
create_rt_data(rt_opts(use_breakpoints = TRUE), breakpoints = rep(1, 10))

# using random walk
create_rt_data(rt_opts(rw = 7), breakpoints = rep(1, 10))

## End(Not run)

Create sampling log message

Description

Internal function that creates a formatted log message describing the sampling parameters. The message format varies by method, with different information shown for exact sampling vs approximate methods (VB, Laplace, Pathfinder). Optionally includes time steps and forecast horizon if present.

Usage

create_sampling_log_message(args, method)

Arguments

Value

A character string containing the formatted log message with a %s placeholder for the id parameter (to be filled by sprintf or flog.debug)

Create Delay Shifted Cases

Description

This functions creates a data frame of reported cases that has been smoothed using a centred partial rolling average (with a period set by smoothing_window) and shifted back in time by some delay. It is used by estimate_infections() to generate the mean shifted prior on which the back calculation method (see backcalc_opts()) is based.

Usage

create_shifted_cases(data, shift, smoothing_window, horizon)

Arguments

Details

The function first shifts all the data back in time by shift days (thus discarding the first shift days of data) and then applies a centred rolling mean of length smoothing_window to the shifted data except for the final period. The final period (the forecast horizon plus half the smoothing window) is instead replaced by a log-linear model fit (with 1 added to the data for fitting to avoid zeroes and later subtracted again), projected to the end of the forecast horizon. The initial part of the data (corresponding to the length of the smoothing window) is then removed, and any non-integer resulting values rounded up.

Value

A ⁠<data.frame>⁠ for shifted reported cases

Examples

## Not run: 
shift <- 7
horizon <- 7
smoothing_window <- 14
## add NAs for horizon
cases <- add_horizon(example_confirmed[1:30], horizon)
## add zeroes initially
cases <- data.table::rbindlist(list(
  data.table::data.table(
    date = seq(
      min(cases$date) - 10,
      min(cases$date) - 1,
      by = "days"
    ),
    confirm = 0, breakpoint = 0
  ),
  cases
))
create_shifted_cases(cases, shift, smoothing_window, horizon)

## End(Not run)

Create a List of Stan Arguments

Description

Generates a list of arguments as required by the stan sampling functions by combining the required options with data, and type of initialisation. Initialisation defaults to random but it is expected that create_initial_conditions() will be used.

Usage

create_stan_args(
  stan = stan_opts(),
  data = NULL,
  init = "random",
  model = "estimate_infections",
  fixed_param = FALSE,
  verbose = FALSE
)

Arguments

Value

A list of stan arguments

Examples

## Not run: 
# default settings
create_stan_args()

# increasing warmup
create_stan_args(stan = stan_opts(warmup = 1000))

## End(Not run)

Create Stan Data Required for estimate_infections

Description

Takes the output of stan_opts() and converts it into a list understood by stan. Internally calls the other create_ family of functions to construct a single list for input into stan with all data required present.

Usage

create_stan_data(data, seeding_time, rt, gp, obs, backcalc, forecast, params)

Arguments

Value

A list of stan data

Examples

## Not run: 
create_stan_data(
  example_confirmed, 7, rt_opts(), gp_opts(), obs_opts(), 7,
  backcalc_opts(), create_shifted_cases(example_confirmed, 7, 14, 7)
)

## End(Not run)

Create delay variables for stan

Description

Create delay variables for stan

Usage

create_stan_delays(..., time_points = 1L)

Arguments

Value

A list of variables as expected by the stan model

Create parameters for stan

Description

Create parameters for stan

Usage

create_stan_params(params)

Arguments

Value

A list of variables as expected by the stan model

Temporary function to support the transition to full support of missing data.

Description

Usage

default_fill_missing_obs(data, obs, obs_column)

Arguments

Value

data set with missing dates filled in as na values

Delay Distribution Options

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

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)

Discretised probability mass function

Description

This function returns the probability mass function of a discretised and truncated distribution defined by distribution type, maximum value and model parameters.

Usage

discrete_pmf(
  distribution = c("exp", "gamma", "lognormal", "normal", "fixed"),
  params,
  max_value,
  cdf_cutoff,
  width
)

Arguments

Value

A vector representing a probability distribution.

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

Discretise a <dist_spec>

Description

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)

Fit an Integer Adjusted Exponential, Gamma or Lognormal distributions

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
)

Get parametric distribution types

Description

Returns the mapping of Stan integer codes to distribution names. Stan uses 0 for lognormal, 1 for gamma.

Usage

dist_spec_distributions()

Value

A character vector of distribution names in Stan order.

Examples

## Not run: 
dist_spec_distributions()
dist_spec_distributions()[1]  # "lognormal"

## End(Not run)

Real-time Rt Estimation, Forecasting and Reporting

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(),
  filter_leading_zeros = TRUE,
  zero_threshold = Inf,
  horizon
)

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)

Load and compile an EpiNow2 cmdstanr model

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.

Load an EpiNow2 rstan model.

Description

The models are pre-compiled upon package install and is returned here.

Usage

epinow2_rstan_model(model = "estimate_infections")

Arguments

Value

An rstan model.

Return a stan model object for the appropriate backend

Description

Return a stan model object for the appropriate backend

Usage

epinow2_stan_model(
  backend = c("rstan", "cmdstanr"),
  model = c("estimate_infections", "simulate_infections", "estimate_secondary",
    "simulate_secondary", "estimate_truncation", "dist_fit")
)

Arguments

Value

A stan model object (either rstan::stanmodel or cmdstanr::CmdStanModel, depending on the backend)

Estimate a Delay Distribution

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

# bootstraps and samples have been reduced for this example
delays <- rlnorm(500, log(5), 1)
estimate_delay(delays, samples = 500, bootstraps = 2)

Estimate Infections, the Time-Varying Reproduction Number and the Rate of Growth

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(),
  CrIs = c(0.2, 0.5, 0.9),
  weigh_delay_priors = TRUE,
  id = "estimate_infections",
  verbose = interactive(),
  filter_leading_zeros = TRUE,
  zero_threshold = Inf,
  horizon
)

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)

Estimate a Secondary Observation from a Primary Observation

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(),
  filter_leading_zeros = FALSE,
  zero_threshold = Inf
)

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)

Estimate Truncation of Observed Data

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

Estimate Cases by Report Date

Description

Either extracts or converts reported cases from an input data table. For output from estimate_infections this is a simple filtering step.

Usage

estimates_by_report_date(
  estimates,
  CrIs = c(0.2, 0.5, 0.9),
  target_folder = NULL,
  samples = TRUE
)

Arguments

Value

A list of samples and summarised estimates of estimated cases by date of report.

Example Confirmed Case Data Set

Description

An example data frame of observed cases

Usage

example_confirmed

Format

A data frame containing cases reported on each date.

Example generation time

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

Example incubation period

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

Example reporting delay

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

Example Case Data Set with Truncation

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.

Expose internal package stan functions in R

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

Extract Credible Intervals Present

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)

Extract delay distributions from a fitted model

Description

Internal helper to extract delay distributions from the ⁠delay_id_*⁠ variables in stan data.

Usage

extract_delay_params(x, stan_data)

Arguments

Value

A named list of dist_spec objects representing the posterior distributions of delay parameters.

Extract samples from all delay parameters

Description

Extracts samples from all delay parameters using the delay ID lookup system. Similar to extract_parameters(), this extracts all delay distribution parameters and uses the *_id variables (e.g., delay_id, trunc_id) to assign meaningful names.

Usage

extract_delays(samples, args)

Arguments

Value

A ⁠<data.table>⁠ with columns: variable, sample, value, or NULL if delay parameters don't exist in the samples

Generate initial conditions from a Stan fit

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.

Extract samples for a latent state from a Stan model

Description

Extracts a time-varying latent state from a list of stan output and returns it as a ⁠<data.table>⁠.

Usage

extract_latent_state(param, samples, dates)

Arguments

Value

A ⁠<data.frame>⁠ containing the following columns:

time

Integer index (1..N) corresponding to the position in the supplied dates vector. This is the row/time-step index that maps to the date column

date

The date corresponding to this time step

sample

Integer sample ID from the posterior

value

Numeric value of the parameter sample

Extract parameter samples from a Stan model

Description

This function has been deprecated. Use format_simulation_output() for simulation outputs or get_samples() for estimation outputs instead.

Usage

extract_parameter_samples(
  stan_fit,
  data,
  reported_dates,
  imputed_dates,
  reported_inf_dates,
  drop_length_1 = FALSE,
  merge = FALSE
)

Arguments

Value

A list of ⁠<data.frame>⁠'s each containing the posterior of a parameter

Extract samples from all parameters

Description

Extract samples from all parameters

Usage

extract_parameters(samples, args)

Arguments

Value

A ⁠<data.table>⁠ with columns: variable, sample, value, or NULL if parameters don't exist in the samples

Extract parameter names

Description

Internal function for extracting given parameter names of a distribution from the environment. Called by new_dist_spec

Usage

extract_params(params, distribution)

Arguments

Value

A character vector of parameters and their values.

Extract all samples from a stan fit

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

Extract scalar parameters from a fitted model

Description

Internal helper to extract scalar parameters (e.g., fraction_observed) from the params array based on ⁠param_id_*⁠ variables.

Usage

extract_scalar_params(x, stan_data)

Arguments

Value

A named list of dist_spec objects representing the posterior distributions of scalar parameters.

Extract a single element of a composite ⁠<dist_spec>⁠

Description

Usage

extract_single_dist(x, i)

Arguments

Value

A single dist_spec object

Examples

dist1 <- LogNormal(mean = 1.6, sd = 0.5, max = 20)

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

# Multiple distributions
## Not run: 
dist <- dist1 + dist2
extract_single_dist(dist, 2)

## End(Not run)

Extract a parameter summary from a Stan object

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.

Fill missing data in a data set to prepare it for use within the package

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)

Filter leading zeros from a data set.

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)

Filter Options for a Target Region

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

Fit a model using the chosen backend.

Description

Internal function for dispatch to fitting with NUTS or VB.

Usage

fit_model(args, id = "stan")

Arguments

Fit a Stan Model using an approximate method

Description

Fits a stan model using variational inference.

Usage

fit_model_approximate(args, future = FALSE, id = "stan")

Arguments

Value

A stan model object

Fit a Stan Model using the NUTs sampler

Description

Fits a stan model using rstan::sampling(). Provides the optional ability to run chains using future with error catching, timeouts and merging of completed chains.

Usage

fit_model_with_nuts(
  args,
  future = FALSE,
  max_execution_time = Inf,
  id = "stan"
)

Arguments

Value

A stan model object

Fix the parameters of a ⁠<dist_spec>⁠

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)

Forecast infections from a given fit and trajectory of the time-varying reproduction number

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)

Forecast options

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)

Forecast Secondary Observations Given a Fit from estimate_secondary

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

Format Posterior Samples

Description

Summaries posterior samples and adds additional custom variables.

Usage

format_fit(posterior_samples, horizon, shift, burn_in, start_date, CrIs)

Arguments

Value

A list of samples and summarised posterior parameter estimates.

Format quantile predictions

Description

Helper function to format posterior samples into quantiles in the structure expected by scoringutils::as_forecast_quantile().

Usage

format_quantile_predictions(samples, quantiles, forecast_date)

Arguments

Value

Data.table with columns: forecast_date, date, horizon, quantile_level, predicted

Format sample predictions

Description

Helper function to format posterior samples into the structure expected by scoringutils::as_forecast_sample().

Usage

format_sample_predictions(samples, forecast_date)

Arguments

Value

Data.table with columns: forecast_date, date, horizon, sample, predicted

Format raw Stan samples with dates and metadata

Description

Internal helper that extracts Stan parameters, adds dates to time-varying parameters, and combines into a single long-format data.table.

Usage

format_samples_with_dates(raw_samples, args, observations)

Arguments

Value

A data.table in long format with dates and metadata

Format Simulation Output from Stan

Description

Formats simulation output from Stan models into structured data.tables with dates. This is an internal function used by simulate_infections() and forecast_infections() to process simulation results.

This differs from get_samples() in that it's designed for simulation outputs which have different array structures (especially with drop_length_1 = TRUE) and need different date ranges for different parameters.

Usage

format_simulation_output(
  stan_fit,
  data,
  reported_dates,
  imputed_dates,
  reported_inf_dates,
  drop_length_1 = FALSE,
  merge = FALSE
)

Arguments

Value

A list of ⁠<data.frame>⁠'s each containing the simulated trajectories of each parameter, or a single merged data.table if merge = TRUE.

Get the distribution of a ⁠<dist_spec>⁠

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)

Extracts an element of a ⁠<dist_spec>⁠

Description

Extracts an element of a ⁠<dist_spec>⁠

Usage

get_element(x, id = NULL, element)

Arguments

Value

The id to use.

Get parameters from distributions or fitted models

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, ...)

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)

Get the probability mass function of a nonparametric distribution

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)

Get predictions from a fitted model

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)

Get a Single Raw Result

Description

Usage

get_raw_result(file, region, date, result_dir)

Arguments

Value

An R object read in from the targeted .rds file

Get Combined Regional Results

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)

Get Folders with Results

Description

Usage

get_regions(results_dir)

Arguments

Value

A named character vector containing the results to plot.

Get Regions with Most Reported Cases

Description

Extract a vector of regions with the most reported cases in a set time window.

Usage

get_regions_with_most_reports(data, time_window = 7, no_regions = 6)

Arguments

Value

A character vector of regions with the highest reported cases

Get posterior samples from a fitted model

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)

Estimate seeding time from delays and generation time

Description

The seeding time is set to the mean of the specified delays, constrained to be at least the maximum generation time

Usage

get_seeding_time(delays, generation_time, rt = rt_opts())

Arguments

Value

An integer seeding time

Approximate Gaussian Process Settings

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,
  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,
  alpha_mean,
  alpha_sd
)

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

Convert Growth Rates to Reproduction numbers.

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)

Generation Time Distribution Options

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)

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

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

Choose a parallel or sequential apply function

Description

Internal function that chooses an appropriate "apply"-type function (either lapply() or future.apply::future_lapply())

Usage

lapply_func(..., backend = "rstan", future.opts = list())

Arguments

Value

A function that can be used to apply a function to a list

Get the lower bounds of the parameters of a distribution

Description

This is used to avoid sampling parameter values that have no support.

Usage

lower_bounds(distribution)

Arguments

Value

A numeric vector, the lower bounds.

Examples

## Not run: 
lower_bounds("lognormal")

## End(Not run)

Format Credible Intervals

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)

Internal function to create a parameter list

Description

Internal function to create a parameter list

Usage

make_param(name, dist = NULL, lower_bound = -Inf)

Arguments

Value

A list with the parameter details, classed as "EpiNow2.param"

Categorise the Probability of Change for Rt

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)

Match User Supplied Arguments with Supported Options

Description

Match user supplied arguments with supported options and return a logical list for internal usage.

Usage

match_output_arguments(
  input_args = NULL,
  supported_args = NULL,
  logger = NULL,
  level = "info"
)

Arguments

Value

A logical vector of named output arguments

Returns the maximum of one or more delay distribution

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)

Returns the mean of one or more delay distribution

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)

Merge truncation predictions with observations for display

Description

Internal function to prepare data for plotting or returning merged predictions and observations. Combines predictions with observed data from each snapshot, including the latest observations as reference.

Usage

merge_trunc_pred_obs(observations, predictions)

Arguments

Value

A ⁠<data.table>⁠ with columns: date, report_date, confirm (observed), last_confirm (from latest snapshot), and prediction columns (median, CrIs).

Get the names of the natural parameters of a distribution

Description

These are the parameters used in the stan models. All other parameter representations are converted to these using convert_to_natural() before being passed to the stan models.

Usage

natural_params(distribution)

Arguments

Value

A character vector, the natural parameters.

Examples

## Not run: 
natural_params("gamma")

## End(Not run)

Calculate the number of distributions in a ⁠<dist_spec>⁠

Description

Calculate the number of distributions in a ⁠<dist_spec>⁠

Usage

ndist(x)

Arguments

Value

The number of distributions.

Internal function for generating a dist_spec given parameters and a distribution.

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

Observation Model Options

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),
  na = c("missing", "accumulate"),
  likelihood = TRUE,
  return_likelihood = FALSE,
  phi
)

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 = Normal(mean = 0.2, sd = 0.02))

Forecast optiong

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

Pads reported cases with daily initial zeros

Description

Pads reported cases with daily initial zeros

Usage

pad_reported_cases(reported_cases, n, with = NA_real_)

Arguments

Value

A data.table of reported cases.

Plot PMF and CDF for a dist_spec 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)

Plot method for estimate_infections

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

Plot method for estimate_secondary

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

Plot method for estimate_truncation

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

Plot method for forecast_infections

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

Plot method for forecast_secondary objects

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

Plot EpiNow2 Credible Intervals

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.

Plot Estimates

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

Plot a Summary of the Latest Results

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

Create a Normal distribution from posterior samples

Description

Helper function to create a Normal distribution from a row of posterior summary statistics, with consistent rounding.

Usage

posterior_to_normal(posterior, idx)

Arguments

Value

A Normal distribution object

Prepare truncation observations for Stan

Description

Internal function to process a list of observation snapshots into the matrix format required by the truncation Stan model.

Usage

prepare_truncation_obs(data, trunc_max)

Arguments

Value

A list containing:

• obs: Matrix of observations (time x datasets)

• obs_dist: Vector of NA counts per dataset (used to determine truncation)

• t: Number of time points

• obs_sets: Number of observation datasets

• dirty_obs: The processed data.tables (ordered by nrow)

Prints the parameters of one or more delay distributions

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)

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

Description

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

Usage

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

Arguments

Value

Invisible

Process regional estimate

Description

Internal function that removes output that is not required, and returns logging information.

Usage

process_region(
  out,
  target_region,
  timing,
  return_output = TRUE,
  return_timing = TRUE,
  complete_logger = "EpiNow2.epinow"
)

Arguments

Value

A list of processed output

See Also

regional_epinow()

Process all Region Estimates

Description

Internal function that processes the output from multiple epinow() runs, adds summary logging information.

Usage

process_regions(regional_out, regions)

Arguments

Value

A list of all regional estimates and successful regional estimates

See Also

regional_epinow() epinow()

Reconstruct a dist_spec from stored stan data and posterior

Description

Reconstruct a dist_spec from stored stan data and posterior

Usage

reconstruct_delay(object, delay_name)

Arguments

Value

A dist_spec object, or NULL if the delay doesn't exist

Reconstruct a nonparametric delay distribution

Description

Helper function to reconstruct a single nonparametric delay component from Stan data. Nonparametric delays are stored as probability mass functions.

Usage

reconstruct_nonparametric(stan_data, np_id)

Arguments

Value

A dist_spec object representing the nonparametric delay

Reconstruct a parametric delay distribution

Description

Helper function to reconstruct a single parametric delay component from Stan data and posterior samples.

Usage

reconstruct_parametric(stan_data, param_id, posterior)

Arguments

Value

A dist_spec object representing the delay distribution

Real-time Rt Estimation, Forecasting and Reporting by Region

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

Arguments

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:40]
cases <- data.table::rbindlist(list(
  data.table::copy(cases)[, region := "testland"],
  cases[, region := "realland"]
))

# run epinow across multiple regions and generate summaries
# samples and warmup have been reduced for this example
# for more examples, see the "estimate_infections examples" vignette
def <- regional_epinow(
  data = cases,
  generation_time = gt_opts(example_generation_time),
  delays = delay_opts(example_incubation_period + example_reporting_delay),
  rt = rt_opts(prior = LogNormal(mean = 2, sd = 0.2)),
  stan = stan_opts(
    samples = 100, warmup = 200
  ),
  verbose = interactive()
)
options(old_opts)

Summarise Regional Runtimes

Description

Used internally by regional_epinow to summarise region run times.

Usage

regional_runtimes(
  regional_output = NULL,
  target_folder = NULL,
  target_date = NULL,
  return_output = FALSE
)

Arguments

Value

A data.table of region run times

See Also

regional_summary() regional_epinow()

Examples

regional_out <- readRDS(system.file(
  package = "EpiNow2", "extdata", "example_regional_epinow.rds"
))
regional_runtimes(regional_output = regional_out$regional)

Regional Summary Output

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

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

Report plots

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

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

Provide Summary Statistics for Estimated Infections and Rt

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

Time-Varying Reproduction Number Options

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 = LogNormal(mean = 1, sd = 1),
  use_rt = TRUE,
  rw = 0,
  use_breakpoints = TRUE,
  future = "latest",
  gp_on = c("R_t-1", "R0"),
  pop = Fixed(0),
  pop_period = c("forecast", "all"),
  pop_floor = 1,
  growth_method = c("infections", "infectiousness")
)

Arguments

Value

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

References

Parag, K. V., Thompson, R. N. & Donnelly, C. A. Are epidemic growth rates more informative than reproduction numbers? Journal of the Royal Statistical Society: Series A (Statistics in Society) 185, S5–S15 (2022).

Examples

# default settings
rt_opts()

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

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

Run epinow with Regional Processing Code

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

Save Estimated Infections

Description

Saves output from estimate_infections to a target directory.

Usage

save_estimate_infections(
  estimates,
  target_folder = NULL,
  samples = TRUE,
  return_fit = TRUE,
  CrIs = c(0.2, 0.5, 0.9)
)

Arguments

Value

No return value, called for side effects

See Also

estimate_infections()

Save Observed Data

Description

Saves observed data to a target location if given.

Usage

save_input(data, target_folder)

Arguments

Value

No return value, called for side effects

Returns the standard deviation of one or more delay distribution

Description

This works out the standard deviation of all the (parametric / nonparametric) delay distributions combined in the passed <dist_spec>. If any of the parameters are themselves uncertain then NA is returned.

Usage

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

Arguments

Value

A vector of standard deviations.

Examples

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

# A gamma distribution with mean 3 and sd 2
dist2 <- Gamma(mean = 3, sd = 2)
sd(dist2)

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

## End(Not run)

Secondary Reports Options

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

Internal helper function to select plots from those created by report_plots()

Description

Internal helper function to select plots from those created by report_plots()

Usage

select_plots(
  plots,
  type = c("summary", "infections", "reports", "R", "growth_rate", "all")
)

Arguments

Value

Selected plots by type

Set to Single Threading

Description

This function sets the threads used by {data.table} to 1 in the parent function and then restores the initial {data.table} threads when the function exits. This is primarily used as an internal function inside of other functions and will generally not be used on its own.

Usage

set_dt_single_thread()

Value

an environment in the parent frame named "dt_settings"

Examples

data.table::setDTthreads(2)
test_function <- function() {
  set_dt_single_thread()

  print(data.table::getDTthreads())
}
test_function()
data.table::getDTthreads()

Setup Default Logging

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

Convert to Data Table

Description

Convenience function that sets the number of {data.table} cores to 1 and maps input to be a {data.table}

Usage

setup_dt(data)

Arguments

Value

A data table

Set up Future Backend

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.

Setup Logging

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

Setup Target Folder for Saving

Description

Sets up a folders for saving results

Usage

setup_target_folder(target_folder = NULL, target_date)

Arguments

Value

A list containing the path to the dated folder and the latest folder

Simulate infections using the renewal equation

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(
  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 = Fixed(0),
  pop_period = c("forecast", "all"),
  pop_floor = 1,
  growth_method = c("infections", "infectiousness")
)

Arguments

Details

In order to simulate, all parameters that are specified such as the mean and standard deviation of delays or observation scaling, must be fixed. Uncertain parameters are not allowed.

Value

A data.table of simulated infections (variable infections) and reported cases (variable reported_cases) by date.

Examples

R <- data.frame(
  date = seq.Date(as.Date("2023-01-01"), length.out = 14, by = "day"),
  R = c(rep(1.2, 7), rep(0.8, 7))
)
sim <- simulate_infections(
  R = R,
  initial_infections = 100,
  generation_time = generation_time_opts(
    fix_parameters(example_generation_time)
  ),
  delays = delay_opts(fix_parameters(example_reporting_delay)),
  obs = obs_opts(family = "poisson")
)

Simulate secondary observations from primary observations

Description

Simulations are done from a given trajectory of primary observations by applying any given delays and observation parameters.

Usage

simulate_secondary(
  primary,
  day_of_week_effect = NULL,
  secondary = secondary_opts(),
  delays = delay_opts(),
  truncation = trunc_opts(),
  obs = obs_opts(),
  CrIs = c(0.2, 0.5, 0.9),
  backend = "rstan"
)

Arguments

Details

In order to simulate, all parameters that are specified such as the mean and standard deviation of delays or observation scaling, must be fixed. Uncertain parameters are not allowed.

A function of the same name that was previously based on a reimplementation of that model in R with potentially time-varying scalings and delays is available as 'convolve_and_scale()

Value

A data.table of simulated secondary observations (column secondary) by date.

Examples

## load data.table to manipulate `example_confirmed` below
library(data.table)
cases <- as.data.table(example_confirmed)[, primary := confirm]
sim <- simulate_secondary(
  cases,
  delays = delay_opts(fix_parameters(example_reporting_delay)),
  obs = obs_opts(family = "poisson")
)

Numerically stable convolution function for two pmf vectors

Description

Unlike stats::convolve(), this function does not use the FFT algorithm, which can generate negative numbers when below machine precision.

Usage

stable_convolve(a, b)

Arguments

Value

A numeric vector representing the convolution of a and b.

Stan Laplace algorithm Options

Description

Defines a list specifying the arguments passed to cmdstanr::laplace().

Usage

stan_laplace_opts(backend = "cmdstanr", trials = 10, ...)

Arguments

Value

A list of arguments to pass to cmdstanr::laplace().

Examples

stan_laplace_opts()

Stan Options

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

stan_opts(
  object = NULL,
  samples = 2000,
  method = c("sampling", "vb", "laplace", "pathfinder"),
  backend = c("rstan", "cmdstanr"),
  return_fit = TRUE,
  ...
)

Arguments