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