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