Title:	Calculate the Final Size of an Epidemic
Version:	0.2.1
Description:	Calculate the final size of a susceptible-infectious-recovered epidemic in a population with demographic variation in contact patterns and susceptibility to disease, as discussed in Miller (2012) <doi:10.1007/s11538-012-9749-6>.
License:	MIT + file LICENSE
URL:	https://github.com/epiverse-trace/finalsize, https://epiverse-trace.github.io/finalsize/
BugReports:	https://github.com/epiverse-trace/finalsize/issues
Depends:	R (≥ 2.10)
Imports:	checkmate, Rcpp
Suggests:	bookdown, colorspace, dplyr, forcats, ggplot2, ggtext, knitr, purrr, rmarkdown, scales, socialmixr, spelling, testthat (≥ 3.0.0), tibble, tidyr, xml2
LinkingTo:	Rcpp, RcppEigen
VignetteBuilder:	knitr
Config/Needs/website:	epiverse-trace/epiversetheme
Config/testthat/edition:	3
Encoding:	UTF-8
Language:	en-GB
LazyData:	true
RoxygenNote:	7.2.3
NeedsCompilation:	yes
Packaged:	2024-04-09 16:21:41 UTC; lshpg6
Author:	Pratik Gupte [aut, cre, cph], Edwin Van Leeuwen [aut, cph], Adam Kucharski [aut, cph], Rosalind Eggo [ctb], Hugo Gruson [ctb], Thibaut Jombart [ctb], Andree Valle-Campos [ctb], Joshua W. Lambert [rev]
Maintainer:	Pratik Gupte <pratik.gupte@lshtm.ac.uk>
Repository:	CRAN
Date/Publication:	2024-04-09 16:40:06 UTC

finalsize: Calculate the Final Size of an Epidemic

Description

Calculate the final size of a susceptible-infectious-recovered epidemic in a population with demographic variation in contact patterns and susceptibility to disease, as discussed in Miller (2012) doi:10.1007/s11538-012-9749-6.

Author(s)

Maintainer: Pratik Gupte pratik.gupte@lshtm.ac.uk (ORCID) [copyright holder]

Authors:

• Edwin Van Leeuwen edwin.vanleeuwen@ukhsa.gov.uk (ORCID) [copyright holder]

• Adam Kucharski adam.kucharski@lshtm.ac.uk (ORCID) [copyright holder]

Other contributors:

• Rosalind Eggo r.eggo@lshtm.ac.uk (ORCID) [contributor]

• Hugo Gruson hugo.gruson@data.org (ORCID) [contributor]

• Thibaut Jombart thibaut@data.org (ORCID) [contributor]

• Andree Valle-Campos andree.valle-campos@lshtm.ac.uk (ORCID) [contributor]

• Joshua W. Lambert joshua.lambert@lshtm.ac.uk (ORCID) [reviewer]

See Also

Useful links:

• https://github.com/epiverse-trace/finalsize

• https://epiverse-trace.github.io/finalsize/

• Report bugs at https://github.com/epiverse-trace/finalsize/issues

Calculate the final size of an epidemic

Description

An internal function that interfaces between the R function final_size() and functions in the package header.

Usage

.final_size(parameters)

Arguments

Final size of an epidemic

Description

final_size calculates the final size of an epidemic outbreak with a given R_0, with options for specifying a population with heterogeneous mixing, and with heterogeneous susceptibility to infection such as that conferred by an immunisation programme.

Usage

final_size(
  r0,
  contact_matrix = matrix(1),
  demography_vector = 1,
  susceptibility = matrix(1),
  p_susceptibility = matrix(1),
  solver = c("iterative", "newton"),
  control = list()
)

Arguments

Details

Specifying heterogeneous mixing and susceptibility

final_size() allows for heterogeneous population mixing and susceptibility, and this is described in the dedicated vignettes:

1. Heterogeneous population mixing: See vignette on "Modelling heterogeneous social contacts" (vignette("varying_contacts", package = "finalsize"));

2. Heterogeneous susceptibility to infection: See vignette on "Modelling heterogeneous susceptibility" (vignette("varying_susceptibility", package = "finalsize")).

Solver options

The control argument accepts a list of solver options, with the iterative solver taking two extra arguments than the Newton solver. This is an optional argument, and default options are used within the solver functions if an argument is missing. Arguments provided override the solver defaults.

Common options

1. iterations: The number of iterations over which to solve for the final size, unless the error is below the solver tolerance. Default = 10000.

2. tolerance: The solver tolerance; solving for final size ends when the error drops below this tolerance. Defaults to set 1e-6. Larger tolerance values are likely to lead to inaccurate final size estimates.

Iterative solver options

1. step_rate: The solver step rate. Defaults to 1.9 as a value found to work well.

2. adapt_step: Boolean, whether the solver step rate should be changed based on the solver error. Defaults to TRUE.

Value

A data.frame of the proportion of infected individuals, within each demography group and susceptibility group combination. If the demography groups and susceptibility groups are named, these names are added to relevant columns. If the groups are not named, synthetic names are added of the form ⁠demo_grp_<i>⁠, for each demographic group i.

Examples

## For a given R_0
r0 <- 2.0
final_size(r0)

## For a population with multiple demographic groups
# load example POLYMOD data included in the package
data(polymod_uk)
contact_matrix <- polymod_uk$contact_matrix
demography_vector <- polymod_uk$demography_vector

# define the number of age and susceptibility groups
n_demo_grps <- length(demography_vector)
n_risk_grps <- 3

# In this example, all risk groups from all age groups are fully
# susceptible, and the final size in each group is influenced only by
# differences in social contacts
susceptibility <- matrix(
  data = 1, nrow = n_demo_grps, ncol = n_risk_grps
)

p_susceptibility <- matrix(
  data = 1, nrow = n_demo_grps, ncol = n_risk_grps
)
# p_susceptibility rows must sum to 1.0
p_susceptibility <- p_susceptibility / rowSums(p_susceptibility)

# using default arguments for `solver` and `control`
final_size(
  r0 = r0,
  contact_matrix = contact_matrix,
  demography_vector = demography_vector,
  susceptibility = susceptibility,
  p_susceptibility = p_susceptibility
)

## Using manually specified solver settings for the iterative solver
control <- list(
  iterations = 100,
  tolerance = 1e-3,
  step_rate = 1.9,
  adapt_step = TRUE
)

final_size(
  r0 = r0,
  contact_matrix = contact_matrix,
  demography_vector = demography_vector,
  susceptibility = susceptibility,
  p_susceptibility = p_susceptibility,
  solver = "iterative",
  control = control
)

## Using manually specified solver settings for the newton solver
control <- list(
  iterations = 100,
  tolerance = 1e-3
)

final_size(
  r0 = r0,
  contact_matrix = contact_matrix,
  demography_vector = demography_vector,
  susceptibility = susceptibility,
  p_susceptibility = p_susceptibility,
  solver = "newton",
  control = control
)

Example POLYMOD social contact data for the U.K.

Description

An example of social contact and demography data for use with finalsize, accessed from the POLYMOD social contacts dataset using the socialmixr package. Data are for the United Kingdom, and age limits are set at 0, 20, and 40 years, with symmetric = TRUE. Code to get these data is given in data-raw/polymod_uk.R.

Usage

polymod_uk

Format

polymod_uk

A list with two named elements:

contact_matrix

A contact matrix with mean contacts between age groups. This matrix is scaled by its largest real eigenvalue, and each row is scaled by the corresponding element in the demography_vector.

demography_vector

A vector with the number of individuals in each of three age groups: 0 – 20, 20 – 40, 40+.

Source

doi:10.1371/journal.pmed.0050074; obtained using socialmixr::polymod. See further methods in data-raw/polymod_uk.R.

Converts between epidemiological parameters related to R_0

Description

Converts between R_0 and the transmission rate \lambda, or calculates the effective reproduction number R_\text{eff} for a population, while accounting for population characteristics including demographic heterogeneity in social contacts, heterogeneity in the demographic distribution, and heterogeneity in susceptibility to infection.

Uses the R0 (R_0), contact matrix (C), population (N), and infectious period (\gamma) to calculate the transmission rate using the following equation.

\lambda = R_0 / ({Max}(EV(C)) \gamma)

where EV(C) denotes the eigenvalues of the matrix C which is calculated from the social contacts matrix scaled by the number of individuals in each demographic and susceptibility group in the population.

Usage

lambda_to_r0(
  lambda,
  contact_matrix,
  demography_vector,
  susceptibility,
  p_susceptibility,
  infectious_period = 1.8
)

r0_to_lambda(
  r0,
  contact_matrix,
  demography_vector,
  susceptibility,
  p_susceptibility,
  infectious_period = 1.8
)

r_eff(r0, contact_matrix, demography_vector, susceptibility, p_susceptibility)

Arguments

Details

Given the transmission rate (\lambda), social contacts matrix (c), demography (N), the distribution P of each demographic group i into susceptibility groups S, and the infectious period (\gamma)

• r_eff() calculates the effective reproductive number;

• lamda_to_r0() calculates the R_0 from the transmission rate as

  R_0 = {Max}(EV(C)) \times \lambda \gamma

• r0_to_lambda() calculates the transmission rate as

  \lambda = R_0 / ({Max}(EV(C)) \gamma)

  Note that this is also called the 'force of infection' and is different from the effective transmission rate often denoted \beta.

Here, EV(C) denotes the eigenvalues of the matrix C which is calculated from the social contacts matrix scaled by the number of individuals in each demographic and susceptibility group in the population.

Value

Returns a single number for the calculated value.

Examples

#### Prepare data ####
# Get example dataset and prepare contact matrix and demography
data(polymod_uk)
contact_matrix <- polymod_uk$contact_matrix
demography_vector <- polymod_uk$demography_vector

# define lambda
lambda <- 0.3

# define infectious period of 5 days
infectious_period <- 5
# define the number of age and susceptibility groups
n_demo_grps <- length(demography_vector)
n_risk_grps <- 3

# In this example, risk varies across groups
susceptibility <- matrix(
  data = c(0.5, 0.7, 1.0), nrow = n_demo_grps, ncol = n_risk_grps
)

# risk does not vary within groups
p_susceptibility <- matrix(
  data = 1, nrow = n_demo_grps, ncol = n_risk_grps
)
# p_susceptibility rows must sum to 1.0
p_susceptibility <- p_susceptibility / rowSums(p_susceptibility)

#### Effective R ####
r0 <- 2.0
r_eff(
  r0 = r0,
  contact_matrix = contact_matrix,
  demography_vector = demography_vector,
  susceptibility = susceptibility,
  p_susceptibility = p_susceptibility
)

#### Transmission rate to R0 ####
lambda_to_r0(
  lambda, contact_matrix, demography_vector,
  susceptibility, p_susceptibility,
  infectious_period
)

#### R0 to Transmission rate ####
r0 <- 1.5
r0_to_lambda(
  r0, contact_matrix, demography_vector,
  susceptibility, p_susceptibility,
  infectious_period
)