modelSSE (version 0.1-3)

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

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

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

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


# \donttest{

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

# }