nmode's Git Repositories - Rnaught/blob - reference/wp.html

   1 <!DOCTYPE html>
   2 <!-- Generated by pkgdown: do not edit by hand --><html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><title>White and Pagano (WP) — wp • Rnaught</title><script src="../deps/jquery-3.6.0/jquery-3.6.0.min.js"></script><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><link href="../deps/bootstrap-5.3.1/bootstrap.min.css" rel="stylesheet"><script src="../deps/bootstrap-5.3.1/bootstrap.bundle.min.js"></script><link href="../deps/font-awesome-6.4.2/css/all.min.css" rel="stylesheet"><link href="../deps/font-awesome-6.4.2/css/v4-shims.min.css" rel="stylesheet"><script src="../deps/headroom-0.11.0/headroom.min.js"></script><script src="../deps/headroom-0.11.0/jQuery.headroom.min.js"></script><script src="../deps/bootstrap-toc-1.0.1/bootstrap-toc.min.js"></script><script src="../deps/clipboard.js-2.0.11/clipboard.min.js"></script><script src="../deps/search-1.0.0/autocomplete.jquery.min.js"></script><script src="../deps/search-1.0.0/fuse.min.js"></script><script src="../deps/search-1.0.0/mark.min.js"></script><!-- pkgdown --><script src="../pkgdown.js"></script><meta property="og:title" content="White and Pagano (WP) — wp"><meta name="description" content="This function implements an R0 estimation due to White and Pagano (Statistics
   3 in Medicine, 2008). The method is based on maximum likelihood estimation in a
   4 Poisson transmission model. See details for important implementation notes."><meta property="og:description" content="This function implements an R0 estimation due to White and Pagano (Statistics
   5 in Medicine, 2008). The method is based on maximum likelihood estimation in a
   6 Poisson transmission model. See details for important implementation notes."><meta property="og:image" content="https://MI2YorkU.github.io/Rnaught/logo.svg"></head><body>
   7     <a href="#main" class="visually-hidden-focusable">Skip to contents</a>
   8
   9
  10     <nav class="navbar navbar-expand-lg fixed-top bg-light" data-bs-theme="light" aria-label="Site navigation"><div class="container">
  11
  12     <a class="navbar-brand me-2" href="../index.html">Rnaught</a>
  13
  14     <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">0.1.0</small>
  15
  16
  17     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
  18       <span class="navbar-toggler-icon"></span>
  19     </button>
  20
  21     <div id="navbar" class="collapse navbar-collapse ms-3">
  22       <ul class="navbar-nav me-auto"><li class="active nav-item"><a class="nav-link" href="../reference/index.html">Reference</a></li>
  23 <li class="nav-item dropdown">
  24   <button class="nav-link dropdown-toggle" type="button" id="dropdown-articles" data-bs-toggle="dropdown" aria-expanded="false" aria-haspopup="true">Articles</button>
  25   <ul class="dropdown-menu" aria-labelledby="dropdown-articles"><li><a class="dropdown-item" href="../articles/seq_bayes_post.html">Sequential Bayes: Utilizing the Posterior Distribution</a></li>
  26     <li><a class="dropdown-item" href="../articles/wp_serial.html">White and Pagano: Utilizing the Serial Distribution</a></li>
  27   </ul></li>
  28       </ul><ul class="navbar-nav"><li class="nav-item"><form class="form-inline" role="search">
  29  <input class="form-control" type="search" name="search-input" id="search-input" autocomplete="off" aria-label="Search site" placeholder="Search for" data-search-index="../search.json"></form></li>
  30 <li class="nav-item"><a class="external-link nav-link" href="https://github.com/MI2YorkU/Rnaught/" aria-label="GitHub"><span class="fa fab fa-github fa-lg"></span></a></li>
  31       </ul></div>
  32
  33
  34   </div>
  35 </nav><div class="container template-reference-topic">
  36 <div class="row">
  37   <main id="main" class="col-md-9"><div class="page-header">
  38       <img src="../logo.svg" class="logo" alt=""><h1>White and Pagano (WP)</h1>
  39       <small class="dont-index">Source: <a href="https://github.com/MI2YorkU/Rnaught/blob/master/R/wp.R" class="external-link"><code>R/wp.R</code></a></small>
  40       <div class="d-none name"><code>wp.Rd</code></div>
  41     </div>
  42
  43     <div class="ref-description section level2">
  44     <p>This function implements an R0 estimation due to White and Pagano (Statistics
  45 in Medicine, 2008). The method is based on maximum likelihood estimation in a
  46 Poisson transmission model. See details for important implementation notes.</p>
  47     </div>
  48
  49     <div class="section level2">
  50     <h2 id="ref-usage">Usage<a class="anchor" aria-label="anchor" href="#ref-usage"></a></h2>
  51     <div class="sourceCode"><pre class="sourceCode r"><code><span><span class="fu">wp</span><span class="op">(</span></span>
  52 <span>  <span class="va">cases</span>,</span>
  53 <span>  mu <span class="op">=</span> <span class="cn">NA</span>,</span>
  54 <span>  serial <span class="op">=</span> <span class="cn">FALSE</span>,</span>
  55 <span>  grid_length <span class="op">=</span> <span class="fl">100</span>,</span>
  56 <span>  max_shape <span class="op">=</span> <span class="fl">10</span>,</span>
  57 <span>  max_scale <span class="op">=</span> <span class="fl">10</span></span>
  58 <span><span class="op">)</span></span></code></pre></div>
  59     </div>
  60
  61     <div class="section level2">
  62     <h2 id="arguments">Arguments<a class="anchor" aria-label="anchor" href="#arguments"></a></h2>
  63
  64
  65 <dl><dt id="arg-cases">cases<a class="anchor" aria-label="anchor" href="#arg-cases"></a></dt>
  66 <dd><p>Vector of case counts. The vector must be of length at least two
  67 and only contain positive integers.</p></dd>
  68
  69
  70 <dt id="arg-mu">mu<a class="anchor" aria-label="anchor" href="#arg-mu"></a></dt>
  71 <dd><p>Mean of the serial distribution (defaults to <code>NA</code>). This must be a
  72 positive number or <code>NA</code>. If a number is specified, the value should match
  73 the case counts in time units. For example, if case counts are weekly and
  74 the serial distribution has a mean of seven days, then <code>mu</code> should be set
  75 to <code>1</code>. If case counts are daily and the serial distribution has a mean of
  76 seven days, then <code>mu</code> should be set to <code>7</code>.</p></dd>
  77
  78
  79 <dt id="arg-serial">serial<a class="anchor" aria-label="anchor" href="#arg-serial"></a></dt>
  80 <dd><p>Whether to return the estimated serial distribution in addition
  81 to the estimate of R0 (defaults to <code>FALSE</code>). This must be a value identical
  82 to <code>TRUE</code> or <code>FALSE</code>.</p></dd>
  83
  84
  85 <dt id="arg-grid-length">grid_length<a class="anchor" aria-label="anchor" href="#arg-grid-length"></a></dt>
  86 <dd><p>The length of the grid in the grid search (defaults to
  87 100). This must be a positive integer. It will only be used if <code>mu</code> is set
  88 to <code>NA</code>. The grid search will go through all combinations of the shape and
  89 scale parameters for the gamma distribution, which are <code>grid_length</code> evenly
  90 spaced values from <code>0</code> (exclusive) to <code>max_shape</code> and <code>max_scale</code>
  91 (inclusive), respectively. Note that larger values will result in a longer
  92 search time.</p></dd>
  93
  94
  95 <dt id="arg-max-shape">max_shape<a class="anchor" aria-label="anchor" href="#arg-max-shape"></a></dt>
  96 <dd><p>The largest possible value of the shape parameter in the
  97 grid search (defaults to 10). This must be a positive number. It will only
  98 be used if <code>mu</code> is set to <code>NA</code>. Note that larger values will result in a
  99 longer search time, and may cause numerical instabilities.</p></dd>
 100
 101
 102 <dt id="arg-max-scale">max_scale<a class="anchor" aria-label="anchor" href="#arg-max-scale"></a></dt>
 103 <dd><p>The largest possible value of the scale parameter in the
 104 grid search (defaults to 10). This must be a positive number. It will only
 105 be used if <code>mu</code> is set to <code>NA</code>. Note that larger values will result in a
 106 longer search time, and may cause numerical instabilities.</p></dd>
 107
 108 </dl></div>
 109     <div class="section level2">
 110     <h2 id="value">Value<a class="anchor" aria-label="anchor" href="#value"></a></h2>
 111     <p>If <code>serial</code> is identical to <code>TRUE</code>, a list containing the following
 112 components is returned:</p><ul><li><p><code>r0</code> - the estimate of R0</p></li>
 113 <li><p><code>supp</code> - the support of the estimated serial distribution</p></li>
 114 <li><p><code>pmf</code> - the probability mass function of the estimated serial
 115 distribution</p></li>
 116 </ul><p>Otherwise, if <code>serial</code> is identical to <code>FALSE</code>, only the estimate of R0 is
 117 returned.</p>
 118     </div>
 119     <div class="section level2">
 120     <h2 id="details">Details<a class="anchor" aria-label="anchor" href="#details"></a></h2>
 121     <p>This method is based on a Poisson transmission model, and hence may be most
 122 most valid at the beginning of an epidemic. In their model, the serial
 123 distribution is assumed to be discrete with a finite number of possible
 124 values. In this implementation, if <code>mu</code> is not <code>NA</code>, the serial distribution
 125 is taken to be a discretized version of a gamma distribution with shape
 126 parameter <code>1</code> and scale parameter <code>mu</code> (and hence mean <code>mu</code>). When <code>mu</code> is
 127 <code>NA</code>, the function implements a grid search algorithm to find the maximum
 128 likelihood estimator over all possible gamma distributions with unknown shape
 129 and scale, restricting these to a prespecified grid (see the parameters
 130 <code>grid_length</code>, <code>max_shape</code> and <code>max_scale</code>). In both cases, the largest value
 131 of the support is chosen such that the cumulative distribution function of
 132 the original (pre-discretized) gamma distribution has cumulative probability
 133 of no more than 0.999 at this value.</p>
 134 <p>When the serial distribution is known (i.e., <code>mu</code> is not <code>NA</code>), sensitivity
 135 testing of <code>mu</code> is strongly recommended. If the serial distribution is
 136 unknown (i.e., <code>mu</code> is <code>NA</code>), the likelihood function can be flat near the
 137 maximum, resulting in numerical instability of the optimizer. When <code>mu</code> is
 138 <code>NA</code>, the implementation takes considerably longer to run. Users should be
 139 careful about units of time (e.g., are counts observed daily or weekly?) when
 140 implementing.</p>
 141 <p>The model developed in White and Pagano (2008) is discrete, and hence the
 142 serial distribution is finite discrete. In our implementation, the input
 143 value <code>mu</code> is that of a continuous distribution. The algorithm discretizes
 144 this input, and so the mean of the estimated serial distribution returned
 145 (when <code>serial</code> is set to <code>TRUE</code>) will differ from <code>mu</code> somewhat. That is to
 146 say, if the user notices that the input <code>mu</code> and the mean of the estimated
 147 serial distribution are different, this is to be expected, and is caused by
 148 the discretization.</p>
 149     </div>
 150     <div class="section level2">
 151     <h2 id="references">References<a class="anchor" aria-label="anchor" href="#references"></a></h2>
 152     <p><a href="https://doi.org/10.1002/sim.3136" class="external-link">White and Pagano (Statistics in Medicine, 2008)</a></p>
 153     </div>
 154     <div class="section level2">
 155     <h2 id="see-also">See also<a class="anchor" aria-label="anchor" href="#see-also"></a></h2>
 156     <div class="dont-index"><p><code><a href="../articles/wp_serial.html">vignette("wp_serial", package="Rnaught")</a></code> for examples of using the
 157 serial distribution.</p></div>
 158     </div>
 159
 160     <div class="section level2">
 161     <h2 id="ref-examples">Examples<a class="anchor" aria-label="anchor" href="#ref-examples"></a></h2>
 162     <div class="sourceCode"><pre class="sourceCode r"><code><span class="r-in"><span><span class="co"># Weekly data.</span></span></span>
 163 <span class="r-in"><span><span class="va">cases</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://rdrr.io/r/base/c.html" class="external-link">c</a></span><span class="op">(</span><span class="fl">1</span>, <span class="fl">4</span>, <span class="fl">10</span>, <span class="fl">5</span>, <span class="fl">3</span>, <span class="fl">4</span>, <span class="fl">19</span>, <span class="fl">3</span>, <span class="fl">3</span>, <span class="fl">14</span>, <span class="fl">4</span><span class="op">)</span></span></span>
 164 <span class="r-in"><span></span></span>
 165 <span class="r-in"><span><span class="co"># Obtain R0 when the serial distribution has a mean of five days.</span></span></span>
 166 <span class="r-in"><span><span class="fu">wp</span><span class="op">(</span><span class="va">cases</span>, mu <span class="op">=</span> <span class="fl">5</span> <span class="op">/</span> <span class="fl">7</span><span class="op">)</span></span></span>
 167 <span class="r-out co"><span class="r-pr">#&gt;</span> [1] 1.107862</span>
 168 <span class="r-in"><span></span></span>
 169 <span class="r-in"><span><span class="co"># Obtain R0 when the serial distribution has a mean of three days.</span></span></span>
 170 <span class="r-in"><span><span class="fu">wp</span><span class="op">(</span><span class="va">cases</span>, mu <span class="op">=</span> <span class="fl">3</span> <span class="op">/</span> <span class="fl">7</span><span class="op">)</span></span></span>
 171 <span class="r-out co"><span class="r-pr">#&gt;</span> [1] 1.067642</span>
 172 <span class="r-in"><span></span></span>
 173 <span class="r-in"><span><span class="co"># Obtain R0 when the serial distribution is unknown.</span></span></span>
 174 <span class="r-in"><span><span class="co"># Note that this will take longer to run than when `mu` is known.</span></span></span>
 175 <span class="r-in"><span><span class="fu">wp</span><span class="op">(</span><span class="va">cases</span><span class="op">)</span></span></span>
 176 <span class="r-out co"><span class="r-pr">#&gt;</span> [1] 1.495574</span>
 177 <span class="r-in"><span></span></span>
 178 <span class="r-in"><span><span class="co"># Same as above, but specify custom grid search parameters. The larger any of</span></span></span>
 179 <span class="r-in"><span><span class="co"># the parameters, the longer the search will take, but with potentially more</span></span></span>
 180 <span class="r-in"><span><span class="co"># accurate estimates.</span></span></span>
 181 <span class="r-in"><span><span class="fu">wp</span><span class="op">(</span><span class="va">cases</span>, grid_length <span class="op">=</span> <span class="fl">40</span>, max_shape <span class="op">=</span> <span class="fl">4</span>, max_scale <span class="op">=</span> <span class="fl">4</span><span class="op">)</span></span></span>
 182 <span class="r-out co"><span class="r-pr">#&gt;</span> [1] 1.495574</span>
 183 <span class="r-in"><span></span></span>
 184 <span class="r-in"><span><span class="co"># Return the estimated serial distribution in addition to the estimate of R0.</span></span></span>
 185 <span class="r-in"><span><span class="va">estimate</span> <span class="op">&lt;-</span> <span class="fu">wp</span><span class="op">(</span><span class="va">cases</span>, serial <span class="op">=</span> <span class="cn">TRUE</span><span class="op">)</span></span></span>
 186 <span class="r-in"><span></span></span>
 187 <span class="r-in"><span><span class="co"># Display the estimate of R0, as well as the support and probability mass</span></span></span>
 188 <span class="r-in"><span><span class="co"># function of the estimated serial distribution returned by the grid search.</span></span></span>
 189 <span class="r-in"><span><span class="va">estimate</span><span class="op">$</span><span class="va">r0</span></span></span>
 190 <span class="r-out co"><span class="r-pr">#&gt;</span> [1] 1.495574</span>
 191 <span class="r-in"><span><span class="va">estimate</span><span class="op">$</span><span class="va">supp</span></span></span>
 192 <span class="r-out co"><span class="r-pr">#&gt;</span>  [1]  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25</span>
 193 <span class="r-in"><span><span class="va">estimate</span><span class="op">$</span><span class="va">pmf</span></span></span>
 194 <span class="r-out co"><span class="r-pr">#&gt;</span>  [1] 0.3295449612 0.1855210503 0.1282030815 0.0920057871 0.0672100630</span>
 195 <span class="r-out co"><span class="r-pr">#&gt;</span>  [6] 0.0496097863 0.0368701329 0.0275354532 0.0206388543 0.0155131855</span>
 196 <span class="r-out co"><span class="r-pr">#&gt;</span> [11] 0.0116867019 0.0088202295 0.0066670102 0.0050459517 0.0038232730</span>
 197 <span class="r-out co"><span class="r-pr">#&gt;</span> [16] 0.0028996361 0.0022009767 0.0016718921 0.0012708261 0.0009665381</span>
 198 <span class="r-out co"><span class="r-pr">#&gt;</span> [21] 0.0007354976 0.0005599523 0.0004264906 0.0003249676 0.0002477014</span>
 199 </code></pre></div>
 200     </div>
 201   </main><aside class="col-md-3"><nav id="toc" aria-label="Table of contents"><h2>On this page</h2>
 202     </nav></aside></div>
 203
 204
 205     <footer><div class="pkgdown-footer-left">
 206   <p>Developed by Sawitree Boonpatcharanon, Jane Heffernan, Hanna Jankowski, Naeem Model.</p>
 207 </div>
 208
 209 <div class="pkgdown-footer-right">
 210   <p>Site built with <a href="https://pkgdown.r-lib.org/" class="external-link">pkgdown</a> 2.1.1.</p>
 211 </div>
 212
 213     </footer></div>
 214
 215
 216
 217
 218
 219   </body></html>
 220