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

   1 % Generated by roxygen2: do not edit by hand
   2 % Please edit documentation in R/seq_bayes.R
   3 \name{seq_bayes}
   4 \alias{seq_bayes}
   5 \title{Sequential Bayes (seqB)}
   6 \usage{
   7 seq_bayes(cases, mu, kappa = 20, post = FALSE)
   8 }
   9 \arguments{
  10 \item{cases}{Vector of case counts. The vector must only contain non-negative
  11 integers, and have at least two positive integers.}
  12
  13 \item{mu}{Mean of the serial distribution. This must be a positive number.
  14 The value should match the case counts in time units. For example, if case
  15 counts are weekly and the serial distribution has a mean of seven days,
  16 then \code{mu} should be set to \code{1}. If case counts are daily and the serial
  17 distribution has a mean of seven days, then \code{mu} should be set to \code{7}.}
  18
  19 \item{kappa}{Largest possible value of the uniform prior (defaults to \code{20}).
  20 This must be a number greater than or equal to \code{1}. It describes the prior
  21 belief on the ranges of R0, and should be set to a higher value if R0 is
  22 believed to be larger.}
  23
  24 \item{post}{Whether to return the posterior distribution of R0 instead of the
  25 estimate of R0 (defaults to \code{FALSE}). This must be a value identical to
  26 \code{TRUE} or \code{FALSE}.}
  27 }
  28 \value{
  29 If \code{post} is identical to \code{TRUE}, a list containing the following
  30 components is returned:
  31 \itemize{
  32 \item \code{supp} - the support of the posterior distribution of R0
  33 \item \code{pmf} - the probability mass function of the posterior distribution of R0
  34 }
  35
  36 Otherwise, if \code{post} is identical to \code{FALSE}, only the estimate of R0 is
  37 returned. Note that the estimate is equal to \code{sum(supp * pmf)} (i.e., the
  38 posterior mean).
  39 }
  40 \description{
  41 This function implements a sequential Bayesian estimation method of R0 due to
  42 Bettencourt and Riberio (PloS One, 2008). See details for important
  43 implementation notes.
  44 }
  45 \details{
  46 The method sets a uniform prior distribution on R0 with possible values
  47 between \code{0} and \code{kappa}, discretized to a fine grid. The distribution of R0
  48 is then updated sequentially, with one update for each new case count
  49 observation. The final estimate of R0 is the mean of the (last) posterior
  50 distribution. The prior distribution is the initial belief of the
  51 distribution of R0, which is the uninformative uniform distribution with
  52 values between \code{0} and \code{kappa}. Users can change the value of \code{kappa} only
  53 (i.e., the prior distribution cannot be changed from the uniform). As more
  54 case counts are observed, the influence of the prior distribution should
  55 lessen on the final estimate.
  56
  57 This method is based on an approximation of the SIR model, which is most
  58 valid at the beginning of an epidemic. The method assumes that the mean of
  59 the serial distribution (sometimes called the serial interval) is known. The
  60 final estimate can be quite sensitive to this value, so sensitivity testing
  61 is strongly recommended. Users should be careful about units of time (e.g.,
  62 are counts observed daily or weekly?) when implementing.
  63
  64 Our code has been modified to provide an estimate even if case counts equal
  65 to zero are present in some time intervals. This is done by grouping the
  66 counts over such periods of time. Without grouping, and in the presence of
  67 zero counts, no estimate can be provided.
  68 }
  69 \examples{
  70 # Weekly data.
  71 cases <- c(1, 4, 10, 5, 3, 4, 19, 3, 3, 14, 4)
  72
  73 # Obtain R0 when the serial distribution has a mean of five days.
  74 seq_bayes(cases, mu = 5 / 7)
  75
  76 # Obtain R0 when the serial distribution has a mean of three days.
  77 seq_bayes(cases, mu = 3 / 7)
  78
  79 # Obtain R0 when the serial distribution has a mean of seven days, and R0 is
  80 # believed to be at most 4.
  81 estimate <- seq_bayes(cases, mu = 1, kappa = 4)
  82
  83 # Same as above, but return the posterior distribution of R0 instead of the
  84 # estimate.
  85 posterior <- seq_bayes(cases, mu = 1, kappa = 4, post = TRUE)
  86
  87 # Display the support and probability mass function of the posterior.
  88 posterior$supp
  89 posterior$pmf
  90
  91 # Note that the following always holds:
  92 estimate == sum(posterior$supp * posterior$pmf)
  93 }
  94 \references{
  95 \href{https://doi.org/10.1371/journal.pone.0002185}{Bettencourt and Riberio (PloS One, 2008)}
  96 }
  97 \seealso{
  98 \code{vignette("seq_bayes_post", package = "Rnaught")} for examples of
  99 using the posterior distribution.
 100 }