d_offspringdistn {modelSSE}

The offspring distribution

Description

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

Usage

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

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

q_offspringdistn(
  p = 0.8,
  epi.para = list(mean = 1, disp = 0.5, shift = 0.2),
  offspring.type = "D",
  lower.tail = TRUE
)

r_offspringdistn(
  n = 10,
  epi.para = list(mean = 1, disp = 0.5, shift = 0.2),
  offspring.type = "D"
)

Arguments

x

A scalar, or a vector of non-negative integer.

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 can be either a scalar, or a vector. For the parameters being assigned with values of vectors, the vectors should be of the same length. 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 non-negative number (not necessarily integer).

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

n

A scalar of positive integer.

Details

For different values of offspring.type,

• When offspring.type = "D", no action to any parameter;

• When offspring.type = "NB", we set parameter shift = 0;

• When offspring.type = "G", we set parameters disp = 1 and shift = 0; and

• When offspring.type = "P", we set parameters disp = +Inf and shift = mean.

Value

For the values returned from the four functions,

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

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

• q_offspringdistn() is the quantile function, and it returns value of quantile (non-negative integer); and

• r_offspringdistn() is the random variable generating function, and it generates a set of n random variables (non-negative integers).

Note

Depending on the values of parameters, the functions could take hours to complete, given the double-summation nature for the Delaporte distribution.

References

Vose D. Risk analysis: a quantitative guide. John Wiley & Sons. 2008; pp. 618-619. ISBN: 978-0-470-51284-5

Lloyd-Smith JO, Schreiber SJ, Kopp PE, Getz WM. Superspreading and the effect of individual variation on disease emergence. Nature. 2005;438(7066):355-359. doi:10.1038/nature04153

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

See Also

Delaporte for the parameterization of Delaporte distribution.

Examples

## Please see the "Usage" section.


## the following returns the proportion of index cases that generated at least 1 offspring cases.
p_offspringdistn(
  q = 0,
  epi.para = list(mean = 1, disp = 0.5, shift = 0.2),
  offspring.type = 'D', lower.tail = FALSE
)

## reproducing the results in Adam, et al. (2020)
## paper doi link: https://doi.org/10.1038/s41591-020-1092-0 (see Fig 3b),
## where the number of offspring cases were fitted
## with parameter R of 0.58 and k of 0.43 under NB distribution.
data(COVID19_JanApr2020_HongKong)
hist(
  COVID19_JanApr2020_HongKong$obs, breaks = c(0:100) -0.5, xlim = c(0,12),
  freq = FALSE, xlab = 'secondary cases', ylab = 'rel. freq.', main = ''
)
lines(0:12, d_offspringdistn(
  x = 0:12,
  epi.para = list(mean = 0.58, disp = 0.43, shift = 0.2),
  offspring.type = "NB"
), pch = 20, type = 'o', lty = 2)


## an example to generate 100 rv of offspring case number
table(r_offspringdistn(
  n = 100,
  epi.para = list(mean = 1, disp = 0.5, shift = 0.2),
  offspring.type = 'D'
))