libs/math/doc/html/math_toolkit/dist_ref/dists/geometric_dist.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Geometric Distribution</title>
   5 <link rel="stylesheet" href="../../../math.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="../../../index.html" title="Math Toolkit 2.11.0">
   8 <link rel="up" href="../dists.html" title="Distributions">
   9 <link rel="prev" href="gamma_dist.html" title="Gamma (and Erlang) Distribution">
  10 <link rel="next" href="hyperexponential_dist.html" title="Hyperexponential Distribution">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="gamma_dist.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="hyperexponential_dist.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h4 class="title">
  27 <a name="math_toolkit.dist_ref.dists.geometric_dist"></a><a class="link" href="geometric_dist.html" title="Geometric Distribution">Geometric
  28         Distribution</a>
  29 </h4></div></div></div>
  30 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">geometric</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
  31 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
  32
  33 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
  34           <span class="keyword">class</span> <a class="link" href="../../../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a>   <span class="special">=</span> <a class="link" href="../../pol_ref/pol_ref_ref.html" title="Policy Class Reference">policies::policy&lt;&gt;</a> <span class="special">&gt;</span>
  35 <span class="keyword">class</span> <span class="identifier">geometric_distribution</span><span class="special">;</span>
  36
  37 <span class="keyword">typedef</span> <span class="identifier">geometric_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">geometric</span><span class="special">;</span>
  38
  39 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&gt;</span>
  40 <span class="keyword">class</span> <span class="identifier">geometric_distribution</span>
  41 <span class="special">{</span>
  42 <span class="keyword">public</span><span class="special">:</span>
  43    <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
  44    <span class="keyword">typedef</span> <span class="identifier">Policy</span>   <span class="identifier">policy_type</span><span class="special">;</span>
  45    <span class="comment">// Constructor from success_fraction:</span>
  46    <span class="identifier">geometric_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">);</span>
  47
  48    <span class="comment">// Parameter accessors:</span>
  49    <span class="identifier">RealType</span> <span class="identifier">success_fraction</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
  50    <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
  51
  52    <span class="comment">// Bounds on success fraction:</span>
  53    <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_lower_bound_on_p</span><span class="special">(</span>
  54       <span class="identifier">RealType</span> <span class="identifier">trials</span><span class="special">,</span>
  55       <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">,</span>
  56       <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">);</span> <span class="comment">// alpha</span>
  57    <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_upper_bound_on_p</span><span class="special">(</span>
  58       <span class="identifier">RealType</span> <span class="identifier">trials</span><span class="special">,</span>
  59       <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">,</span>
  60       <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">);</span> <span class="comment">// alpha</span>
  61
  62    <span class="comment">// Estimate min/max number of trials:</span>
  63    <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_minimum_number_of_trials</span><span class="special">(</span>
  64       <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span>     <span class="comment">// Number of failures.</span>
  65       <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span>     <span class="comment">// Success fraction.</span>
  66       <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">);</span> <span class="comment">// Probability threshold alpha.</span>
  67    <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_maximum_number_of_trials</span><span class="special">(</span>
  68       <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span>     <span class="comment">// Number of failures.</span>
  69       <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span>     <span class="comment">// Success fraction.</span>
  70       <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">);</span> <span class="comment">// Probability threshold alpha.</span>
  71 <span class="special">};</span>
  72
  73 <span class="special">}}</span> <span class="comment">// namespaces</span>
  74 </pre>
  75 <p>
  76           The class type <code class="computeroutput"><span class="identifier">geometric_distribution</span></code>
  77           represents a <a href="http://en.wikipedia.org/wiki/geometric_distribution" target="_top">geometric
  78           distribution</a>: it is used when there are exactly two mutually exclusive
  79           outcomes of a <a href="http://en.wikipedia.org/wiki/Bernoulli_trial" target="_top">Bernoulli
  80           trial</a>: these outcomes are labelled "success" and "failure".
  81         </p>
  82 <p>
  83           For <a href="http://en.wikipedia.org/wiki/Bernoulli_trial" target="_top">Bernoulli
  84           trials</a> each with success fraction <span class="emphasis"><em>p</em></span>, the geometric
  85           distribution gives the probability of observing <span class="emphasis"><em>k</em></span>
  86           trials (failures, events, occurrences, or arrivals) before the first success.
  87         </p>
  88 <div class="note"><table border="0" summary="Note">
  89 <tr>
  90 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
  91 <th align="left">Note</th>
  92 </tr>
  93 <tr><td align="left" valign="top"><p>
  94             For this implementation, the set of trials <span class="bold"><strong>includes
  95             zero</strong></span> (unlike another definition where the set of trials starts
  96             at one, sometimes named <span class="emphasis"><em>shifted</em></span>).
  97           </p></td></tr>
  98 </table></div>
  99 <p>
 100           The geometric distribution assumes that success_fraction <span class="emphasis"><em>p</em></span>
 101           is fixed for all <span class="emphasis"><em>k</em></span> trials.
 102         </p>
 103 <p>
 104           The probability that there are <span class="emphasis"><em>k</em></span> failures before the
 105           first success
 106         </p>
 107 <div class="blockquote"><blockquote class="blockquote"><p>
 108             <span class="serif_italic">Pr(Y=<span class="emphasis"><em>k</em></span>) = (1-<span class="emphasis"><em>p</em></span>)<sup><span class="emphasis"><em>k</em></span></sup> <span class="emphasis"><em>p</em></span></span>
 109           </p></blockquote></div>
 110 <p>
 111           For example, when throwing a 6-face dice the success probability <span class="emphasis"><em>p</em></span>
 112           = 1/6 = 0.1666&#8202;&#775;. Throwing repeatedly until a <span class="emphasis"><em>three</em></span>
 113           appears, the probability distribution of the number of times <span class="emphasis"><em>not-a-three</em></span>
 114           is thrown is geometric.
 115         </p>
 116 <p>
 117           Geometric distribution has the Probability Density Function PDF:
 118         </p>
 119 <div class="blockquote"><blockquote class="blockquote"><p>
 120             <span class="serif_italic">(1-<span class="emphasis"><em>p</em></span>)<sup><span class="emphasis"><em>k</em></span></sup> <span class="emphasis"><em>p</em></span></span>
 121           </p></blockquote></div>
 122 <p>
 123           The following graph illustrates how the PDF and CDF vary for three examples
 124           of the success fraction <span class="emphasis"><em>p</em></span>, (when considering the geometric
 125           distribution as a continuous function),
 126         </p>
 127 <div class="blockquote"><blockquote class="blockquote"><p>
 128             <span class="inlinemediaobject"><img src="../../../../graphs/geometric_pdf_2.svg" align="middle"></span>
 129
 130           </p></blockquote></div>
 131 <div class="blockquote"><blockquote class="blockquote"><p>
 132             <span class="inlinemediaobject"><img src="../../../../graphs/geometric_cdf_2.svg" align="middle"></span>
 133
 134           </p></blockquote></div>
 135 <p>
 136           and as discrete.
 137         </p>
 138 <div class="blockquote"><blockquote class="blockquote"><p>
 139             <span class="inlinemediaobject"><img src="../../../../graphs/geometric_pdf_discrete.svg" align="middle"></span>
 140
 141           </p></blockquote></div>
 142 <div class="blockquote"><blockquote class="blockquote"><p>
 143             <span class="inlinemediaobject"><img src="../../../../graphs/geometric_cdf_discrete.svg" align="middle"></span>
 144
 145           </p></blockquote></div>
 146 <h5>
 147 <a name="math_toolkit.dist_ref.dists.geometric_dist.h0"></a>
 148           <span class="phrase"><a name="math_toolkit.dist_ref.dists.geometric_dist.related_distributions"></a></span><a class="link" href="geometric_dist.html#math_toolkit.dist_ref.dists.geometric_dist.related_distributions">Related
 149           Distributions</a>
 150         </h5>
 151 <p>
 152           The geometric distribution is a special case of the <a class="link" href="negative_binomial_dist.html" title="Negative Binomial Distribution">Negative
 153           Binomial Distribution</a> with successes parameter <span class="emphasis"><em>r</em></span>
 154           = 1, so only one first and only success is required : thus by definition
 155           &#8192;&#8192; <code class="computeroutput"><span class="identifier">geometric</span><span class="special">(</span><span class="identifier">p</span><span class="special">)</span> <span class="special">==</span>
 156           <span class="identifier">negative_binomial</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="identifier">p</span><span class="special">)</span></code>
 157         </p>
 158 <pre class="programlisting"><span class="identifier">negative_binomial_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">r</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">success_fraction</span><span class="special">);</span>
 159 <span class="identifier">negative_binomial</span> <span class="identifier">nb</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="identifier">success_fraction</span><span class="special">);</span>
 160 <span class="identifier">geometric</span> <span class="identifier">g</span><span class="special">(</span><span class="identifier">success_fraction</span><span class="special">);</span>
 161 <span class="identifier">ASSERT</span><span class="special">(</span><span class="identifier">pdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="number">1</span><span class="special">)</span> <span class="special">==</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">g</span><span class="special">,</span> <span class="number">1</span><span class="special">));</span>
 162 </pre>
 163 <p>
 164           This implementation uses real numbers for the computation throughout (because
 165           it uses the <span class="bold"><strong>real-valued</strong></span> power and exponential
 166           functions). So to obtain a conventional strictly-discrete geometric distribution
 167           you must ensure that an integer value is provided for the number of trials
 168           (random variable) <span class="emphasis"><em>k</em></span>, and take integer values (floor
 169           or ceil functions) from functions that return a number of successes.
 170         </p>
 171 <div class="caution"><table border="0" summary="Caution">
 172 <tr>
 173 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../doc/src/images/caution.png"></td>
 174 <th align="left">Caution</th>
 175 </tr>
 176 <tr><td align="left" valign="top">
 177 <p>
 178             The geometric distribution is a discrete distribution: internally, functions
 179             like the <code class="computeroutput"><span class="identifier">cdf</span></code> and <code class="computeroutput"><span class="identifier">pdf</span></code> are treated "as if" they
 180             are continuous functions, but in reality the results returned from these
 181             functions only have meaning if an integer value is provided for the random
 182             variate argument.
 183           </p>
 184 <p>
 185             The quantile function will by default return an integer result that has
 186             been <span class="emphasis"><em>rounded outwards</em></span>. That is to say lower quantiles
 187             (where the probability is less than 0.5) are rounded downward, and upper
 188             quantiles (where the probability is greater than 0.5) are rounded upwards.
 189             This behaviour ensures that if an X% quantile is requested, then <span class="emphasis"><em>at
 190             least</em></span> the requested coverage will be present in the central
 191             region, and <span class="emphasis"><em>no more than</em></span> the requested coverage
 192             will be present in the tails.
 193           </p>
 194 <p>
 195             This behaviour can be changed so that the quantile functions are rounded
 196             differently, or even return a real-valued result using <a class="link" href="../../pol_overview.html" title="Policy Overview">Policies</a>.
 197             It is strongly recommended that you read the tutorial <a class="link" href="../../pol_tutorial/understand_dis_quant.html" title="Understanding Quantiles of Discrete Distributions">Understanding
 198             Quantiles of Discrete Distributions</a> before using the quantile
 199             function on the geometric distribution. The <a class="link" href="../../pol_ref/discrete_quant_ref.html" title="Discrete Quantile Policies">reference
 200             docs</a> describe how to change the rounding policy for these distributions.
 201           </p>
 202 </td></tr>
 203 </table></div>
 204 <h5>
 205 <a name="math_toolkit.dist_ref.dists.geometric_dist.h1"></a>
 206           <span class="phrase"><a name="math_toolkit.dist_ref.dists.geometric_dist.member_functions"></a></span><a class="link" href="geometric_dist.html#math_toolkit.dist_ref.dists.geometric_dist.member_functions">Member
 207           Functions</a>
 208         </h5>
 209 <h6>
 210 <a name="math_toolkit.dist_ref.dists.geometric_dist.h2"></a>
 211           <span class="phrase"><a name="math_toolkit.dist_ref.dists.geometric_dist.constructor"></a></span><a class="link" href="geometric_dist.html#math_toolkit.dist_ref.dists.geometric_dist.constructor">Constructor</a>
 212         </h6>
 213 <pre class="programlisting"><span class="identifier">geometric_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">);</span>
 214 </pre>
 215 <p>
 216           Constructor: <span class="emphasis"><em>p</em></span> or success_fraction is the probability
 217           of success of a single trial.
 218         </p>
 219 <p>
 220           Requires: <code class="computeroutput"><span class="number">0</span> <span class="special">&lt;=</span>
 221           <span class="identifier">p</span> <span class="special">&lt;=</span>
 222           <span class="number">1</span></code>.
 223         </p>
 224 <h6>
 225 <a name="math_toolkit.dist_ref.dists.geometric_dist.h3"></a>
 226           <span class="phrase"><a name="math_toolkit.dist_ref.dists.geometric_dist.accessors"></a></span><a class="link" href="geometric_dist.html#math_toolkit.dist_ref.dists.geometric_dist.accessors">Accessors</a>
 227         </h6>
 228 <pre class="programlisting"><span class="identifier">RealType</span> <span class="identifier">success_fraction</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> <span class="comment">// successes / trials (0 &lt;= p &lt;= 1)</span>
 229 </pre>
 230 <p>
 231           Returns the success_fraction parameter <span class="emphasis"><em>p</em></span> from which
 232           this distribution was constructed.
 233         </p>
 234 <pre class="programlisting"><span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> <span class="comment">// required successes always one,</span>
 235 <span class="comment">// included for compatibility with negative binomial distribution</span>
 236 <span class="comment">// with successes r == 1.</span>
 237 </pre>
 238 <p>
 239           Returns unity.
 240         </p>
 241 <p>
 242           The following functions are equivalent to those provided for the negative
 243           binomial, with successes = 1, but are provided here for completeness.
 244         </p>
 245 <p>
 246           The best method of calculation for the following functions is disputed:
 247           see <a class="link" href="binomial_dist.html" title="Binomial Distribution">Binomial
 248           Distribution</a> and <a class="link" href="negative_binomial_dist.html" title="Negative Binomial Distribution">Negative
 249           Binomial Distribution</a> for more discussion.
 250         </p>
 251 <h6>
 252 <a name="math_toolkit.dist_ref.dists.geometric_dist.h4"></a>
 253           <span class="phrase"><a name="math_toolkit.dist_ref.dists.geometric_dist.lower_bound_on_success_fraction_"></a></span><a class="link" href="geometric_dist.html#math_toolkit.dist_ref.dists.geometric_dist.lower_bound_on_success_fraction_">Lower
 254           Bound on success_fraction Parameter <span class="emphasis"><em>p</em></span></a>
 255         </h6>
 256 <pre class="programlisting"><span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_lower_bound_on_p</span><span class="special">(</span>
 257   <span class="identifier">RealType</span> <span class="identifier">failures</span><span class="special">,</span>
 258   <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">)</span> <span class="comment">// (0 &lt;= alpha &lt;= 1), 0.05 equivalent to 95% confidence.</span>
 259 </pre>
 260 <p>
 261           Returns a <span class="bold"><strong>lower bound</strong></span> on the success fraction:
 262         </p>
 263 <div class="variablelist">
 264 <p class="title"><b></b></p>
 265 <dl class="variablelist">
 266 <dt><span class="term">failures</span></dt>
 267 <dd><p>
 268                 The total number of failures before the 1st success.
 269               </p></dd>
 270 <dt><span class="term">alpha</span></dt>
 271 <dd><p>
 272                 The largest acceptable probability that the true value of the success
 273                 fraction is <span class="bold"><strong>less than</strong></span> the value
 274                 returned.
 275               </p></dd>
 276 </dl>
 277 </div>
 278 <p>
 279           For example, if you observe <span class="emphasis"><em>k</em></span> failures from <span class="emphasis"><em>n</em></span>
 280           trials the best estimate for the success fraction is simply 1/<span class="emphasis"><em>n</em></span>,
 281           but if you want to be 95% sure that the true value is <span class="bold"><strong>greater
 282           than</strong></span> some value, <span class="emphasis"><em>p<sub>min</sub></em></span>, then:
 283         </p>
 284 <pre class="programlisting"><span class="identifier">p</span><sub>min</sub> <span class="special">=</span> <span class="identifier">geometric_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span>
 285    <span class="identifier">find_lower_bound_on_p</span><span class="special">(</span><span class="identifier">failures</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span>
 286 </pre>
 287 <p>
 288           <a class="link" href="../../stat_tut/weg/neg_binom_eg/neg_binom_conf.html" title="Calculating Confidence Limits on the Frequency of Occurrence for the Negative Binomial Distribution">See
 289           negative_binomial confidence interval example.</a>
 290         </p>
 291 <p>
 292           This function uses the Clopper-Pearson method of computing the lower bound
 293           on the success fraction, whilst many texts refer to this method as giving
 294           an "exact" result in practice it produces an interval that guarantees
 295           <span class="emphasis"><em>at least</em></span> the coverage required, and may produce pessimistic
 296           estimates for some combinations of <span class="emphasis"><em>failures</em></span> and <span class="emphasis"><em>successes</em></span>.
 297           See:
 298         </p>
 299 <p>
 300           <a href="http://www.ucs.louisiana.edu/~kxk4695/Discrete_new.pdf" target="_top">Yong
 301           Cai and K. Krishnamoorthy, A Simple Improved Inferential Method for Some
 302           Discrete Distributions. Computational statistics and data analysis, 2005,
 303           vol. 48, no3, 605-621</a>.
 304         </p>
 305 <h6>
 306 <a name="math_toolkit.dist_ref.dists.geometric_dist.h5"></a>
 307           <span class="phrase"><a name="math_toolkit.dist_ref.dists.geometric_dist.upper_bound_on_success_fraction_"></a></span><a class="link" href="geometric_dist.html#math_toolkit.dist_ref.dists.geometric_dist.upper_bound_on_success_fraction_">Upper
 308           Bound on success_fraction Parameter p</a>
 309         </h6>
 310 <pre class="programlisting"><span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_upper_bound_on_p</span><span class="special">(</span>
 311    <span class="identifier">RealType</span> <span class="identifier">trials</span><span class="special">,</span>
 312    <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">);</span> <span class="comment">// (0 &lt;= alpha &lt;= 1), 0.05 equivalent to 95% confidence.</span>
 313 </pre>
 314 <p>
 315           Returns an <span class="bold"><strong>upper bound</strong></span> on the success
 316           fraction:
 317         </p>
 318 <div class="variablelist">
 319 <p class="title"><b></b></p>
 320 <dl class="variablelist">
 321 <dt><span class="term">trials</span></dt>
 322 <dd><p>
 323                 The total number of trials conducted.
 324               </p></dd>
 325 <dt><span class="term">alpha</span></dt>
 326 <dd><p>
 327                 The largest acceptable probability that the true value of the success
 328                 fraction is <span class="bold"><strong>greater than</strong></span> the value
 329                 returned.
 330               </p></dd>
 331 </dl>
 332 </div>
 333 <p>
 334           For example, if you observe <span class="emphasis"><em>k</em></span> successes from <span class="emphasis"><em>n</em></span>
 335           trials the best estimate for the success fraction is simply <span class="emphasis"><em>k/n</em></span>,
 336           but if you want to be 95% sure that the true value is <span class="bold"><strong>less
 337           than</strong></span> some value, <span class="emphasis"><em>p<sub>max</sub></em></span>, then:
 338         </p>
 339 <pre class="programlisting"><span class="identifier">p</span><sub>max</sub> <span class="special">=</span> <span class="identifier">geometric_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span><span class="identifier">find_upper_bound_on_p</span><span class="special">(</span>
 340                     <span class="identifier">k</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span>
 341 </pre>
 342 <p>
 343           <a class="link" href="../../stat_tut/weg/neg_binom_eg/neg_binom_conf.html" title="Calculating Confidence Limits on the Frequency of Occurrence for the Negative Binomial Distribution">See
 344           negative binomial confidence interval example.</a>
 345         </p>
 346 <p>
 347           This function uses the Clopper-Pearson method of computing the lower bound
 348           on the success fraction, whilst many texts refer to this method as giving
 349           an "exact" result in practice it produces an interval that guarantees
 350           <span class="emphasis"><em>at least</em></span> the coverage required, and may produce pessimistic
 351           estimates for some combinations of <span class="emphasis"><em>failures</em></span> and <span class="emphasis"><em>successes</em></span>.
 352           See:
 353         </p>
 354 <p>
 355           <a href="http://www.ucs.louisiana.edu/~kxk4695/Discrete_new.pdf" target="_top">Yong
 356           Cai and K. Krishnamoorthy, A Simple Improved Inferential Method for Some
 357           Discrete Distributions. Computational statistics and data analysis, 2005,
 358           vol. 48, no3, 605-621</a>.
 359         </p>
 360 <h6>
 361 <a name="math_toolkit.dist_ref.dists.geometric_dist.h6"></a>
 362           <span class="phrase"><a name="math_toolkit.dist_ref.dists.geometric_dist.estimating_number_of_trials_to_e"></a></span><a class="link" href="geometric_dist.html#math_toolkit.dist_ref.dists.geometric_dist.estimating_number_of_trials_to_e">Estimating
 363           Number of Trials to Ensure at Least a Certain Number of Failures</a>
 364         </h6>
 365 <pre class="programlisting"><span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_minimum_number_of_trials</span><span class="special">(</span>
 366    <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span>     <span class="comment">// number of failures.</span>
 367    <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span>     <span class="comment">// success fraction.</span>
 368    <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">);</span> <span class="comment">// probability threshold (0.05 equivalent to 95%).</span>
 369 </pre>
 370 <p>
 371           This functions estimates the number of trials required to achieve a certain
 372           probability that <span class="bold"><strong>more than <span class="emphasis"><em>k</em></span>
 373           failures will be observed</strong></span>.
 374         </p>
 375 <div class="variablelist">
 376 <p class="title"><b></b></p>
 377 <dl class="variablelist">
 378 <dt><span class="term">k</span></dt>
 379 <dd><p>
 380                 The target number of failures to be observed.
 381               </p></dd>
 382 <dt><span class="term">p</span></dt>
 383 <dd><p>
 384                 The probability of <span class="emphasis"><em>success</em></span> for each trial.
 385               </p></dd>
 386 <dt><span class="term">alpha</span></dt>
 387 <dd><p>
 388                 The maximum acceptable <span class="emphasis"><em>risk</em></span> that only <span class="emphasis"><em>k</em></span>
 389                 failures or fewer will be observed.
 390               </p></dd>
 391 </dl>
 392 </div>
 393 <p>
 394           For example:
 395         </p>
 396 <pre class="programlisting"><span class="identifier">geometric_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span><span class="identifier">find_minimum_number_of_trials</span><span class="special">(</span><span class="number">10</span><span class="special">,</span> <span class="number">0.5</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span>
 397 </pre>
 398 <p>
 399           Returns the smallest number of trials we must conduct to be 95% (1-0.05)
 400           sure of seeing 10 failures that occur with frequency one half.
 401         </p>
 402 <p>
 403           <a class="link" href="../../stat_tut/weg/neg_binom_eg/neg_binom_size_eg.html" title="Estimating Sample Sizes for the Negative Binomial.">Worked
 404           Example.</a>
 405         </p>
 406 <p>
 407           This function uses numeric inversion of the geometric distribution to obtain
 408           the result: another interpretation of the result is that it finds the number
 409           of trials (failures) that will lead to an <span class="emphasis"><em>alpha</em></span> probability
 410           of observing <span class="emphasis"><em>k</em></span> failures or fewer.
 411         </p>
 412 <h6>
 413 <a name="math_toolkit.dist_ref.dists.geometric_dist.h7"></a>
 414           <span class="phrase"><a name="math_toolkit.dist_ref.dists.geometric_dist.estimating_number_of_trials_to_0"></a></span><a class="link" href="geometric_dist.html#math_toolkit.dist_ref.dists.geometric_dist.estimating_number_of_trials_to_0">Estimating
 415           Number of Trials to Ensure a Maximum Number of Failures or Less</a>
 416         </h6>
 417 <pre class="programlisting"><span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_maximum_number_of_trials</span><span class="special">(</span>
 418    <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span>     <span class="comment">// number of failures.</span>
 419    <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span>     <span class="comment">// success fraction.</span>
 420    <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">);</span> <span class="comment">// probability threshold (0.05 equivalent to 95%).</span>
 421 </pre>
 422 <p>
 423           This functions estimates the maximum number of trials we can conduct and
 424           achieve a certain probability that <span class="bold"><strong>k failures or
 425           fewer will be observed</strong></span>.
 426         </p>
 427 <div class="variablelist">
 428 <p class="title"><b></b></p>
 429 <dl class="variablelist">
 430 <dt><span class="term">k</span></dt>
 431 <dd><p>
 432                 The maximum number of failures to be observed.
 433               </p></dd>
 434 <dt><span class="term">p</span></dt>
 435 <dd><p>
 436                 The probability of <span class="emphasis"><em>success</em></span> for each trial.
 437               </p></dd>
 438 <dt><span class="term">alpha</span></dt>
 439 <dd><p>
 440                 The maximum acceptable <span class="emphasis"><em>risk</em></span> that more than
 441                 <span class="emphasis"><em>k</em></span> failures will be observed.
 442               </p></dd>
 443 </dl>
 444 </div>
 445 <p>
 446           For example:
 447         </p>
 448 <pre class="programlisting"><span class="identifier">geometric_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span><span class="identifier">find_maximum_number_of_trials</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">1.0</span><span class="special">-</span><span class="number">1.0</span><span class="special">/</span><span class="number">1000000</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span>
 449 </pre>
 450 <p>
 451           Returns the largest number of trials we can conduct and still be 95% sure
 452           of seeing no failures that occur with frequency one in one million.
 453         </p>
 454 <p>
 455           This function uses numeric inversion of the geometric distribution to obtain
 456           the result: another interpretation of the result, is that it finds the
 457           number of trials that will lead to an <span class="emphasis"><em>alpha</em></span> probability
 458           of observing more than k failures.
 459         </p>
 460 <h5>
 461 <a name="math_toolkit.dist_ref.dists.geometric_dist.h8"></a>
 462           <span class="phrase"><a name="math_toolkit.dist_ref.dists.geometric_dist.non_member_accessors"></a></span><a class="link" href="geometric_dist.html#math_toolkit.dist_ref.dists.geometric_dist.non_member_accessors">Non-member
 463           Accessors</a>
 464         </h5>
 465 <p>
 466           All the <a class="link" href="../nmp.html" title="Non-Member Properties">usual non-member accessor
 467           functions</a> that are generic to all distributions are supported:
 468           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.cdf">Cumulative Distribution Function</a>,
 469           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.pdf">Probability Density Function</a>,
 470           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.quantile">Quantile</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.hazard">Hazard Function</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.chf">Cumulative Hazard Function</a>,
 471           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.mean">mean</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.median">median</a>,
 472           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.mode">mode</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.variance">variance</a>,
 473           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.sd">standard deviation</a>,
 474           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.skewness">skewness</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.kurtosis">kurtosis</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.kurtosis_excess">kurtosis_excess</a>,
 475           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.range">range</a> and <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.support">support</a>.
 476         </p>
 477 <p>
 478           However it's worth taking a moment to define what these actually mean in
 479           the context of this distribution:
 480         </p>
 481 <div class="table">
 482 <a name="math_toolkit.dist_ref.dists.geometric_dist.meaning_of_the_non_member_access"></a><p class="title"><b>Table&#160;5.2.&#160;Meaning of the non-member accessors.</b></p>
 483 <div class="table-contents"><table class="table" summary="Meaning of the non-member accessors.">
 484 <colgroup>
 485 <col>
 486 <col>
 487 </colgroup>
 488 <thead><tr>
 489 <th>
 490                   <p>
 491                     Function
 492                   </p>
 493                 </th>
 494 <th>
 495                   <p>
 496                     Meaning
 497                   </p>
 498                 </th>
 499 </tr></thead>
 500 <tbody>
 501 <tr>
 502 <td>
 503                   <p>
 504                     <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.pdf">Probability Density
 505                     Function</a>
 506                   </p>
 507                 </td>
 508 <td>
 509                   <p>
 510                     The probability of obtaining <span class="bold"><strong>exactly k
 511                     failures</strong></span> from <span class="emphasis"><em>k</em></span> trials with success
 512                     fraction p. For example:
 513                   </p>
 514 <pre class="programlisting"><span class="identifier">pdf</span><span class="special">(</span><span class="identifier">geometric</span><span class="special">(</span><span class="identifier">p</span><span class="special">),</span> <span class="identifier">k</span><span class="special">)</span></pre>
 515                 </td>
 516 </tr>
 517 <tr>
 518 <td>
 519                   <p>
 520                     <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.cdf">Cumulative Distribution
 521                     Function</a>
 522                   </p>
 523                 </td>
 524 <td>
 525                   <p>
 526                     The probability of obtaining <span class="bold"><strong>k failures
 527                     or fewer</strong></span> from <span class="emphasis"><em>k</em></span> trials with success
 528                     fraction p and success on the last trial. For example:
 529                   </p>
 530 <pre class="programlisting"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">geometric</span><span class="special">(</span><span class="identifier">p</span><span class="special">),</span> <span class="identifier">k</span><span class="special">)</span></pre>
 531                 </td>
 532 </tr>
 533 <tr>
 534 <td>
 535                   <p>
 536                     <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.ccdf">Complement of
 537                     the Cumulative Distribution Function</a>
 538                   </p>
 539                 </td>
 540 <td>
 541                   <p>
 542                     The probability of obtaining <span class="bold"><strong>more than
 543                     k failures</strong></span> from <span class="emphasis"><em>k</em></span> trials with
 544                     success fraction p and success on the last trial. For example:
 545                   </p>
 546 <pre class="programlisting"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">geometric</span><span class="special">(</span><span class="identifier">p</span><span class="special">),</span> <span class="identifier">k</span><span class="special">))</span></pre>
 547                 </td>
 548 </tr>
 549 <tr>
 550 <td>
 551                   <p>
 552                     <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.quantile">Quantile</a>
 553                   </p>
 554                 </td>
 555 <td>
 556                   <p>
 557                     The <span class="bold"><strong>greatest</strong></span> number of failures
 558                     <span class="emphasis"><em>k</em></span> expected to be observed from <span class="emphasis"><em>k</em></span>
 559                     trials with success fraction <span class="emphasis"><em>p</em></span>, at probability
 560                     <span class="emphasis"><em>P</em></span>. Note that the value returned is a real-number,
 561                     and not an integer. Depending on the use case you may want to
 562                     take either the floor or ceiling of the real result. For example:
 563                   </p>
 564 <pre class="programlisting"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">geometric</span><span class="special">(</span><span class="identifier">p</span><span class="special">),</span> <span class="identifier">P</span><span class="special">)</span></pre>
 565                 </td>
 566 </tr>
 567 <tr>
 568 <td>
 569                   <p>
 570                     <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.quantile_c">Quantile
 571                     from the complement of the probability</a>
 572                   </p>
 573                 </td>
 574 <td>
 575                   <p>
 576                     The <span class="bold"><strong>smallest</strong></span> number of failures
 577                     <span class="emphasis"><em>k</em></span> expected to be observed from <span class="emphasis"><em>k</em></span>
 578                     trials with success fraction <span class="emphasis"><em>p</em></span>, at probability
 579                     <span class="emphasis"><em>P</em></span>. Note that the value returned is a real-number,
 580                     and not an integer. Depending on the use case you may want to
 581                     take either the floor or ceiling of the real result. For example:
 582                   </p>
 583 <pre class="programlisting"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">geometric</span><span class="special">(</span><span class="identifier">p</span><span class="special">),</span> <span class="identifier">P</span><span class="special">))</span></pre>
 584                 </td>
 585 </tr>
 586 </tbody>
 587 </table></div>
 588 </div>
 589 <br class="table-break"><h5>
 590 <a name="math_toolkit.dist_ref.dists.geometric_dist.h9"></a>
 591           <span class="phrase"><a name="math_toolkit.dist_ref.dists.geometric_dist.accuracy"></a></span><a class="link" href="geometric_dist.html#math_toolkit.dist_ref.dists.geometric_dist.accuracy">Accuracy</a>
 592         </h5>
 593 <p>
 594           This distribution is implemented using the pow and exp functions, so most
 595           results are accurate within a few epsilon for the RealType. For extreme
 596           values of <code class="computeroutput"><span class="keyword">double</span></code> <span class="emphasis"><em>p</em></span>,
 597           for example 0.9999999999, accuracy can fall significantly, for example
 598           to 10 decimal digits (from 16).
 599         </p>
 600 <h5>
 601 <a name="math_toolkit.dist_ref.dists.geometric_dist.h10"></a>
 602           <span class="phrase"><a name="math_toolkit.dist_ref.dists.geometric_dist.implementation"></a></span><a class="link" href="geometric_dist.html#math_toolkit.dist_ref.dists.geometric_dist.implementation">Implementation</a>
 603         </h5>
 604 <p>
 605           In the following table, <span class="emphasis"><em>p</em></span> is the probability that
 606           any one trial will be successful (the success fraction), <span class="emphasis"><em>k</em></span>
 607           is the number of failures, <span class="emphasis"><em>p</em></span> is the probability and
 608           <span class="emphasis"><em>q = 1-p</em></span>, <span class="emphasis"><em>x</em></span> is the given probability
 609           to estimate the expected number of failures using the quantile.
 610         </p>
 611 <div class="informaltable"><table class="table">
 612 <colgroup>
 613 <col>
 614 <col>
 615 </colgroup>
 616 <thead><tr>
 617 <th>
 618                   <p>
 619                     Function
 620                   </p>
 621                 </th>
 622 <th>
 623                   <p>
 624                     Implementation Notes
 625                   </p>
 626                 </th>
 627 </tr></thead>
 628 <tbody>
 629 <tr>
 630 <td>
 631                   <p>
 632                     pdf
 633                   </p>
 634                 </td>
 635 <td>
 636                   <p>
 637                     pdf = p * pow(q, k)
 638                   </p>
 639                 </td>
 640 </tr>
 641 <tr>
 642 <td>
 643                   <p>
 644                     cdf
 645                   </p>
 646                 </td>
 647 <td>
 648                   <p>
 649                     cdf = 1 - q<sup>k=1</sup>
 650                   </p>
 651                 </td>
 652 </tr>
 653 <tr>
 654 <td>
 655                   <p>
 656                     cdf complement
 657                   </p>
 658                 </td>
 659 <td>
 660                   <p>
 661                     exp(log1p(-p) * (k+1))
 662                   </p>
 663                 </td>
 664 </tr>
 665 <tr>
 666 <td>
 667                   <p>
 668                     quantile
 669                   </p>
 670                 </td>
 671 <td>
 672                   <p>
 673                     k = log1p(-x) / log1p(-p) -1
 674                   </p>
 675                 </td>
 676 </tr>
 677 <tr>
 678 <td>
 679                   <p>
 680                     quantile from the complement
 681                   </p>
 682                 </td>
 683 <td>
 684                   <p>
 685                     k = log(x) / log1p(-p) -1
 686                   </p>
 687                 </td>
 688 </tr>
 689 <tr>
 690 <td>
 691                   <p>
 692                     mean
 693                   </p>
 694                 </td>
 695 <td>
 696                   <p>
 697                     (1-p)/p
 698                   </p>
 699                 </td>
 700 </tr>
 701 <tr>
 702 <td>
 703                   <p>
 704                     variance
 705                   </p>
 706                 </td>
 707 <td>
 708                   <p>
 709                     (1-p)/p&#178;
 710                   </p>
 711                 </td>
 712 </tr>
 713 <tr>
 714 <td>
 715                   <p>
 716                     mode
 717                   </p>
 718                 </td>
 719 <td>
 720                   <p>
 721                     0
 722                   </p>
 723                 </td>
 724 </tr>
 725 <tr>
 726 <td>
 727                   <p>
 728                     skewness
 729                   </p>
 730                 </td>
 731 <td>
 732                   <p>
 733                     (2-p)/&#8730;q
 734                   </p>
 735                 </td>
 736 </tr>
 737 <tr>
 738 <td>
 739                   <p>
 740                     kurtosis
 741                   </p>
 742                 </td>
 743 <td>
 744                   <p>
 745                     9+p&#178;/q
 746                   </p>
 747                 </td>
 748 </tr>
 749 <tr>
 750 <td>
 751                   <p>
 752                     kurtosis excess
 753                   </p>
 754                 </td>
 755 <td>
 756                   <p>
 757                     6 +p&#178;/q
 758                   </p>
 759                 </td>
 760 </tr>
 761 <tr>
 762 <td>
 763                   <p>
 764                     parameter estimation member functions
 765                   </p>
 766                 </td>
 767 <td>
 768                   <p>
 769                     See <a class="link" href="negative_binomial_dist.html" title="Negative Binomial Distribution">Negative
 770                     Binomial Distribution</a>
 771                   </p>
 772                 </td>
 773 </tr>
 774 <tr>
 775 <td>
 776                   <p>
 777                     <code class="computeroutput"><span class="identifier">find_lower_bound_on_p</span></code>
 778                   </p>
 779                 </td>
 780 <td>
 781                   <p>
 782                     See <a class="link" href="negative_binomial_dist.html" title="Negative Binomial Distribution">Negative
 783                     Binomial Distribution</a>
 784                   </p>
 785                 </td>
 786 </tr>
 787 <tr>
 788 <td>
 789                   <p>
 790                     <code class="computeroutput"><span class="identifier">find_upper_bound_on_p</span></code>
 791                   </p>
 792                 </td>
 793 <td>
 794                   <p>
 795                     See <a class="link" href="negative_binomial_dist.html" title="Negative Binomial Distribution">Negative
 796                     Binomial Distribution</a>
 797                   </p>
 798                 </td>
 799 </tr>
 800 <tr>
 801 <td>
 802                   <p>
 803                     <code class="computeroutput"><span class="identifier">find_minimum_number_of_trials</span></code>
 804                   </p>
 805                 </td>
 806 <td>
 807                   <p>
 808                     See <a class="link" href="negative_binomial_dist.html" title="Negative Binomial Distribution">Negative
 809                     Binomial Distribution</a>
 810                   </p>
 811                 </td>
 812 </tr>
 813 <tr>
 814 <td>
 815                   <p>
 816                     <code class="computeroutput"><span class="identifier">find_maximum_number_of_trials</span></code>
 817                   </p>
 818                 </td>
 819 <td>
 820                   <p>
 821                     See <a class="link" href="negative_binomial_dist.html" title="Negative Binomial Distribution">Negative
 822                     Binomial Distribution</a>
 823                   </p>
 824                 </td>
 825 </tr>
 826 </tbody>
 827 </table></div>
 828 </div>
 829 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 830 <td align="left"></td>
 831 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2019 Nikhar
 832       Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
 833       Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
 834       R&#229;de, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
 835       Daryle Walker and Xiaogang Zhang<p>
 836         Distributed under the Boost Software License, Version 1.0. (See accompanying
 837         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 838       </p>
 839 </div></td>
 840 </tr></table>
 841 <hr>
 842 <div class="spirit-nav">
 843 <a accesskey="p" href="gamma_dist.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="hyperexponential_dist.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 844 </div>
 845 </body>
 846 </html>