d_outbreakdistn: The final outbreak size distribution

In modelSSE: Modelling Infectious Disease Superspreading from Contact Tracing Data

The final outbreak size distribution

Description

Density, cumulative distribution, quantile, and random variable generating functions for the final outbreak size distribution with pre-defined epidemiological parameters.

Usage

d_outbreakdistn(
  x = 10,
  seed.size = 1,
  epi.para = list(mean = 1, disp = 0.5, shift = 0.2),
  offspring.type = "D",
  is.log = FALSE
)

p_outbreakdistn(
  q = 30.5,
  seed.size = 1,
  epi.para = list(mean = 1, disp = 0.5, shift = 0.2),
  offspring.type = "D",
  lower.tail = TRUE,
  is.log = FALSE
)

q_outbreakdistn(
  p = 0.8,
  seed.size = 1,
  epi.para = list(mean = 1, disp = 0.5, shift = 0.2),
  offspring.type = "D",
  lower.tail = TRUE,
  upr.limit = 1000
)

r_outbreakdistn(
  n = 10,
  seed.size = 1,
  epi.para = list(mean = 1, disp = 0.5, shift = 0.2),
  offspring.type = "D",
  upr.limit = 1000
)

Arguments

x	A scalar, or a vector of final outbreak size, which is positive integer. The value of x must be not less than seed.size.
seed.size	A scalar, or a vector of positive integer. For vector type of seed.size, it only applies to d_outbreakdistn(), and p_outbreakdistn(). If seed.size and x or q are vectors, seed.size should be of the same length as x or q.
epi.para	A list (list) of pre-defined epidemiological parameters for offspring distribution, in the format of list(mean = ?, disp = ?, shift = ?), where the three parameters accept non-negative values. Each parameter must be a scalar. For Delaporte distribution, the value of mean should be larger than the value of shift.
offspring.type	A character label (character) indicating the type of distribution used to describe the offspring distribution. It only accepts one of the following values: "D" indicates the Delaporte distribution, "NB" indicates the negative binomial distribution, "G" indicates the geometric distribution, or "P" indicates the Poisson distribution. By default, offspring.type = 'D'.
is.log	A logical variable, under which probability would be taken natural logarithm, if is.log = TRUE. By default, is.log = FALSE.
q	A scalar, or a vector of positive number (not necessarily integer). The value of q must be not less than seed.size.
lower.tail	A logical variable, under which the probability is cumulative distribution function (CDF, i.e., P(X <= x)), if lower.tail = TRUE, and otherwise, 1 - CDF (i.e., P(X > x)). By default, lower.tail = TRUE.
p	A scalar, or a vector of probability (i.e., ranging from 0 to 1).
upr.limit	A positive integer. If the result final outbreak size is larger than upr.limit, the returned value will be set as "> upr.limit". The value of upr.limit must be larger than seed.size. By default, upr.limit = 1000, and no need to change the default setting here unless for special reasons.
n	A scalar of positive integer.

Details

Function d_outbreakdistn() returns the probability of having an outbreak with final size x generated by seed.size index cases, where (seed.size) is given.

Function p_outbreakdistn() returns the probability of having an outbreak with final size less than or equal to, or larger than q (depending on the value of lower.tail), generated by seed.size index cases, where (seed.size) is given.

Function q_outbreakdistn() returns a value such that there is a probability of p for having a final outbreak size less than or equal to, or larger than this value (depending on the value of lower.tail) generated by seed.size index cases, where (seed.size) is given.

Function r_outbreakdistn() returns a set of n random variables of final outbreak size, given (seed.size).

Value

For the values returned from the four functions,

• d_outbreakdistn() is the probability mass function (PMF), and it returns value of probability (i.e., ranging from 0 to 1);

• p_outbreakdistn() is the cumulative distribution function (CDF), and it returns value of probability (i.e., ranging from 0 to 1);

• q_outbreakdistn() is the quantile function, and it returns value of quantile (positive integer); and

• r_outbreakdistn() is the random variable generating function, and it generates a set of n random variables (positive integers).

Specially, due to the computational consumption, an upper limit was set for the functions q_outbreakdistn() and r_outbreakdistn(), i.e., upr.limit, and thus, both functions here return value in string form (i.e., character).

Note

Each parameter in epi.para = list(mean = ?, disp = ?, shift = ?) should be a scalar, which means vector is not allowed here.

When q is large, e.g., q > 10000, the function p_outbreakdistn() could take few seconds, or even minutes to complete.

When upr.limit is large, e.g., upr.limit > 10000, the functions q_outbreakdistn() and r_outbreakdistn() could take few seconds, or even minutes to complete. Thus, we do not recommend the users to change the default setting of upr.limit unless for special reasons.

References

Farrington CP, Kanaan MN, Gay NJ. Branching process models for surveillance of infectious diseases controlled by mass vaccination. Biostatistics. 2003;4(2):279-95. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1093/biostatistics/4.2.279")}

Nishiura H, Yan P, Sleeman CK, Mode CJ. Estimating the transmission potential of supercritical processes based on the final size distribution of minor outbreaks. Journal of Theoretical Biology. 2012;294:48-55. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/j.jtbi.2011.10.039")}

Blumberg S, Funk S, Pulliam JR. Detecting differential transmissibilities that affect the size of self-limited outbreaks. PLoS Pathogens. 2014;10(10):e1004452. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1371/journal.ppat.1004452")}

Kucharski AJ, Althaus CL. The role of superspreading in Middle East respiratory syndrome coronavirus (MERS-CoV) transmission. Eurosurveillance. 2015;20(25):21167. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.2807/1560-7917.ES2015.20.25.21167")}

Endo A, Abbott S, Kucharski AJ, Funk S. Estimating the overdispersion in COVID-19 transmission using outbreak sizes outside China. Wellcome Open Research. 2020;5:67. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.12688/wellcomeopenres.15842.3")}

Zhao S, Chong MK, Ryu S, Guo Z, He M, Chen B, Musa SS, Wang J, Wu Y, He D, Wang MH. Characterizing superspreading potential of infectious disease: Decomposition of individual transmissibility. PLoS Computational Biology. 2022;18(6):e1010281. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1371/journal.pcbi.1010281")}

See Also

d_offspringdistn

Examples

## an example to generate 1000 rv of final outbreak size
table(r_outbreakdistn(
  n = 1000,
  seed.size = 1,
  epi.para = list(mean = 1, disp = 0.5, shift = 0.2),
  offspring.type = "D",
  upr.limit = 10
))




## an attempt to reproduce the results in Guo, et al. (2022)
## paper doi link: https://doi.org/10.1016/j.jinf.2022.05.041 (see Fig 1B),
## where the probability of one seed case generating an outbreak with final size >= a given number,
## with parameter R of 0.78 and k of 0.10 under NB distribution.
plot(1:100, 1 - c(0,cumsum(d_outbreakdistn(
  x = 1:99,
  seed.size = 1,
  epi.para = list(mean = 0.78, disp = 0.10, shift = 0.2),
  offspring.type = "NB",
))), log = 'y', type = 'l', xlab = 'outbreak size', ylab = 'probability')
plot(1:100, c(1,p_outbreakdistn(
  q = 1:99,
  seed.size = 1,
  epi.para = list(mean = 0.78, disp = 0.10, shift = 0.2),
  offspring.type = "NB",
  lower.tail = FALSE
)), log = 'y', type = 'l', xlab = 'outbreak size', ylab = 'probability')

modelSSE documentation built on Sept. 8, 2023, 5:52 p.m.