nmode's Git Repositories - Rnaught/blob - man/wp.Rd

   1 % Generated by roxygen2: do not edit by hand
   2 % Please edit documentation in R/wp.R
   3 \name{wp}
   4 \alias{wp}
   5 \title{White and Pagano (WP)}
   6 \usage{
   7 wp(
   8   cases,
   9   mu = NA,
  10   serial = FALSE,
  11   grid_length = 100,
  12   max_shape = 10,
  13   max_scale = 10
  14 )
  15 }
  16 \arguments{
  17 \item{cases}{Vector of case counts. The vector must be of length at least two
  18 and only contain positive integers.}
  19
  20 \item{mu}{Mean of the serial distribution (defaults to \code{NA}). This must be a
  21 positive number or \code{NA}. If a number is specified, the value should match
  22 the case counts in time units. For example, if case counts are weekly and
  23 the serial distribution has a mean of seven days, then \code{mu} should be set
  24 to \code{1}. If case counts are daily and the serial distribution has a mean of
  25 seven days, then \code{mu} should be set to \code{7}.}
  26
  27 \item{serial}{Whether to return the estimated serial distribution in addition
  28 to the estimate of R0 (defaults to \code{FALSE}). This must be a value identical
  29 to \code{TRUE} or \code{FALSE}.}
  30
  31 \item{grid_length}{The length of the grid in the grid search (defaults to
  32 100). This must be a positive integer. It will only be used if \code{mu} is set
  33 to \code{NA}. The grid search will go through all combinations of the shape and
  34 scale parameters for the gamma distribution, which are \code{grid_length} evenly
  35 spaced values from \code{0} (exclusive) to \code{max_shape} and \code{max_scale}
  36 (inclusive), respectively. Note that larger values will result in a longer
  37 search time.}
  38
  39 \item{max_shape}{The largest possible value of the shape parameter in the
  40 grid search (defaults to 10). This must be a positive number. It will only
  41 be used if \code{mu} is set to \code{NA}. Note that larger values will result in a
  42 longer search time, and may cause numerical instabilities.}
  43
  44 \item{max_scale}{The largest possible value of the scale parameter in the
  45 grid search (defaults to 10). This must be a positive number. It will only
  46 be used if \code{mu} is set to \code{NA}. Note that larger values will result in a
  47 longer search time, and may cause numerical instabilities.}
  48 }
  49 \value{
  50 If \code{serial} is identical to \code{TRUE}, a list containing the following
  51 components is returned:
  52 \itemize{
  53 \item \code{r0} - the estimate of R0
  54 \item \code{supp} - the support of the estimated serial distribution
  55 \item \code{pmf} - the probability mass function of the estimated serial
  56 distribution
  57 }
  58
  59 Otherwise, if \code{serial} is identical to \code{FALSE}, only the estimate of R0 is
  60 returned.
  61 }
  62 \description{
  63 This function implements an R0 estimation due to White and Pagano (Statistics
  64 in Medicine, 2008). The method is based on maximum likelihood estimation in a
  65 Poisson transmission model. See details for important implementation notes.
  66 }
  67 \details{
  68 This method is based on a Poisson transmission model, and hence may be most
  69 most valid at the beginning of an epidemic. In their model, the serial
  70 distribution is assumed to be discrete with a finite number of possible
  71 values. In this implementation, if \code{mu} is not \code{NA}, the serial distribution
  72 is taken to be a discretized version of a gamma distribution with shape
  73 parameter \code{1} and scale parameter \code{mu} (and hence mean \code{mu}). When \code{mu} is
  74 \code{NA}, the function implements a grid search algorithm to find the maximum
  75 likelihood estimator over all possible gamma distributions with unknown shape
  76 and scale, restricting these to a prespecified grid (see the parameters
  77 \code{grid_length}, \code{max_shape} and \code{max_scale}). In both cases, the largest value
  78 of the support is chosen such that the cumulative distribution function of
  79 the original (pre-discretized) gamma distribution has cumulative probability
  80 of no more than 0.999 at this value.
  81
  82 When the serial distribution is known (i.e., \code{mu} is not \code{NA}), sensitivity
  83 testing of \code{mu} is strongly recommended. If the serial distribution is
  84 unknown (i.e., \code{mu} is \code{NA}), the likelihood function can be flat near the
  85 maximum, resulting in numerical instability of the optimizer. When \code{mu} is
  86 \code{NA}, the implementation takes considerably longer to run. Users should be
  87 careful about units of time (e.g., are counts observed daily or weekly?) when
  88 implementing.
  89
  90 The model developed in White and Pagano (2008) is discrete, and hence the
  91 serial distribution is finite discrete. In our implementation, the input
  92 value \code{mu} is that of a continuous distribution. The algorithm discretizes
  93 this input, and so the mean of the estimated serial distribution returned
  94 (when \code{serial} is set to \code{TRUE}) will differ from \code{mu} somewhat. That is to
  95 say, if the user notices that the input \code{mu} and the mean of the estimated
  96 serial distribution are different, this is to be expected, and is caused by
  97 the discretization.
  98 }
  99 \examples{
 100 # Weekly data.
 101 cases <- c(1, 4, 10, 5, 3, 4, 19, 3, 3, 14, 4)
 102
 103 # Obtain R0 when the serial distribution has a mean of five days.
 104 wp(cases, mu = 5 / 7)
 105
 106 # Obtain R0 when the serial distribution has a mean of three days.
 107 wp(cases, mu = 3 / 7)
 108
 109 # Obtain R0 when the serial distribution is unknown.
 110 # Note that this will take longer to run than when `mu` is known.
 111 wp(cases)
 112
 113 # Same as above, but specify custom grid search parameters. The larger any of
 114 # the parameters, the longer the search will take, but with potentially more
 115 # accurate estimates.
 116 wp(cases, grid_length = 40, max_shape = 4, max_scale = 4)
 117
 118 # Return the estimated serial distribution in addition to the estimate of R0.
 119 estimate <- wp(cases, serial = TRUE)
 120
 121 # Display the estimate of R0, as well as the support and probability mass
 122 # function of the estimated serial distribution returned by the grid search.
 123 estimate$r0
 124 estimate$supp
 125 estimate$pmf
 126 }
 127 \references{
 128 \href{https://doi.org/10.1002/sim.3136}{White and Pagano (Statistics in Medicine, 2008)}
 129 }
 130 \seealso{
 131 \code{vignette("wp_serial", package="Rnaught")} for examples of using the
 132 serial distribution.
 133 }