R: The final outbreak size distribution

d_outbreakdistn {modelSSE}

R Documentation

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. 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. 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. 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. 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. 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. doi:10.1371/journal.pcbi.1010281

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

[Package modelSSE version 0.1-3 Index]