1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Negative Binomial 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.12.0"> 8<link rel="up" href="../dists.html" title="Distributions"> 9<link rel="prev" href="lognormal_dist.html" title="Log Normal Distribution"> 10<link rel="next" href="nc_beta_dist.html" title="Noncentral Beta 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="lognormal_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="nc_beta_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.negative_binomial_dist"></a><a class="link" href="negative_binomial_dist.html" title="Negative Binomial Distribution">Negative 28 Binomial Distribution</a> 29</h4></div></div></div> 30<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</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">negative_binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></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"><</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 21. 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<></a> <span class="special">></span> 35<span class="keyword">class</span> <span class="identifier">negative_binomial_distribution</span><span class="special">;</span> 36 37<span class="keyword">typedef</span> <span class="identifier">negative_binomial_distribution</span><span class="special"><></span> <span class="identifier">negative_binomial</span><span class="special">;</span> 38 39<span class="keyword">template</span> <span class="special"><</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 21. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">></span> 40<span class="keyword">class</span> <span class="identifier">negative_binomial_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 successes and success_fraction:</span> 46 <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">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">negative_binomial_distribution</span></code> 77 represents a <a href="http://en.wikipedia.org/wiki/Negative_binomial_distribution" target="_top">negative_binomial 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 k + r Bernoulli trials each with success fraction p, the negative_binomial 84 distribution gives the probability of observing k failures and r successes 85 with success on the last trial. The negative_binomial distribution assumes 86 that success_fraction p is fixed for all (k + r) trials. 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 The random variable for the negative binomial distribution is the number 95 of trials, (the number of successes is a fixed property of the distribution) 96 whereas for the binomial, the random variable is the number of successes, 97 for a fixed number of trials. 98 </p></td></tr> 99</table></div> 100<p> 101 It has the PDF: 102 </p> 103<div class="blockquote"><blockquote class="blockquote"><p> 104 <span class="inlinemediaobject"><img src="../../../../equations/neg_binomial_ref.svg"></span> 105 106 </p></blockquote></div> 107<p> 108 The following graph illustrate how the PDF varies as the success fraction 109 <span class="emphasis"><em>p</em></span> changes: 110 </p> 111<div class="blockquote"><blockquote class="blockquote"><p> 112 <span class="inlinemediaobject"><img src="../../../../graphs/negative_binomial_pdf_1.svg" align="middle"></span> 113 114 </p></blockquote></div> 115<p> 116 Alternatively, this graph shows how the shape of the PDF varies as the 117 number of successes changes: 118 </p> 119<div class="blockquote"><blockquote class="blockquote"><p> 120 <span class="inlinemediaobject"><img src="../../../../graphs/negative_binomial_pdf_2.svg" align="middle"></span> 121 122 </p></blockquote></div> 123<h5> 124<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h0"></a> 125 <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.related_distributions"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.related_distributions">Related 126 Distributions</a> 127 </h5> 128<p> 129 The name negative binomial distribution is reserved by some to the case 130 where the successes parameter r is an integer. This integer version is 131 also called the <a href="http://mathworld.wolfram.com/PascalDistribution.html" target="_top">Pascal 132 distribution</a>. 133 </p> 134<p> 135 This implementation uses real numbers for the computation throughout (because 136 it uses the <span class="bold"><strong>real-valued</strong></span> incomplete beta 137 function family of functions). This real-valued version is also called 138 the Polya Distribution. 139 </p> 140<p> 141 The Poisson distribution is a generalization of the Pascal distribution, 142 where the success parameter r is an integer: to obtain the Pascal distribution 143 you must ensure that an integer value is provided for r, and take integer 144 values (floor or ceiling) from functions that return a number of successes. 145 </p> 146<p> 147 For large values of r (successes), the negative binomial distribution converges 148 to the Poisson distribution. 149 </p> 150<p> 151 The geometric distribution is a special case where the successes parameter 152 r = 1, so only a first and only success is required. geometric(p) = negative_binomial(1, 153 p). 154 </p> 155<p> 156 The Poisson distribution is a special case for large successes 157 </p> 158<p> 159 poisson(λ) = lim <sub>r → ∞</sub> negative_binomial(r, r / (λ + r))) 160 </p> 161<div class="caution"><table border="0" summary="Caution"> 162<tr> 163<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../doc/src/images/caution.png"></td> 164<th align="left">Caution</th> 165</tr> 166<tr><td align="left" valign="top"> 167<p> 168 The Negative Binomial distribution is a discrete distribution: internally, 169 functions like the <code class="computeroutput"><span class="identifier">cdf</span></code> 170 and <code class="computeroutput"><span class="identifier">pdf</span></code> are treated "as 171 if" they are continuous functions, but in reality the results returned 172 from these functions only have meaning if an integer value is provided 173 for the random variate argument. 174 </p> 175<p> 176 The quantile function will by default return an integer result that has 177 been <span class="emphasis"><em>rounded outwards</em></span>. That is to say lower quantiles 178 (where the probability is less than 0.5) are rounded downward, and upper 179 quantiles (where the probability is greater than 0.5) are rounded upwards. 180 This behaviour ensures that if an X% quantile is requested, then <span class="emphasis"><em>at 181 least</em></span> the requested coverage will be present in the central 182 region, and <span class="emphasis"><em>no more than</em></span> the requested coverage 183 will be present in the tails. 184 </p> 185<p> 186 This behaviour can be changed so that the quantile functions are rounded 187 differently, or even return a real-valued result using <a class="link" href="../../pol_overview.html" title="Policy Overview">Policies</a>. 188 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 189 Quantiles of Discrete Distributions</a> before using the quantile 190 function on the Negative Binomial distribution. The <a class="link" href="../../pol_ref/discrete_quant_ref.html" title="Discrete Quantile Policies">reference 191 docs</a> describe how to change the rounding policy for these distributions. 192 </p> 193</td></tr> 194</table></div> 195<h5> 196<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h1"></a> 197 <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.member_functions"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.member_functions">Member 198 Functions</a> 199 </h5> 200<h6> 201<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h2"></a> 202 <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.construct"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.construct">Construct</a> 203 </h6> 204<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">p</span><span class="special">);</span> 205</pre> 206<p> 207 Constructor: <span class="emphasis"><em>r</em></span> is the total number of successes, 208 <span class="emphasis"><em>p</em></span> is the probability of success of a single trial. 209 </p> 210<p> 211 Requires: <code class="computeroutput"><span class="identifier">r</span> <span class="special">></span> 212 <span class="number">0</span></code> and <code class="computeroutput"><span class="number">0</span> 213 <span class="special"><=</span> <span class="identifier">p</span> 214 <span class="special"><=</span> <span class="number">1</span></code>. 215 </p> 216<h6> 217<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h3"></a> 218 <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.accessors"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.accessors">Accessors</a> 219 </h6> 220<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 <= p <= 1)</span> 221</pre> 222<p> 223 Returns the parameter <span class="emphasis"><em>p</em></span> from which this distribution 224 was constructed. 225 </p> 226<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 (r > 0)</span> 227</pre> 228<p> 229 Returns the parameter <span class="emphasis"><em>r</em></span> from which this distribution 230 was constructed. 231 </p> 232<p> 233 The best method of calculation for the following functions is disputed: 234 see <a class="link" href="binomial_dist.html" title="Binomial Distribution">Binomial 235 Distribution</a> for more discussion. 236 </p> 237<h6> 238<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h4"></a> 239 <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.lower_bound_on_parameter_p"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.lower_bound_on_parameter_p">Lower 240 Bound on Parameter p</a> 241 </h6> 242<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> 243 <span class="identifier">RealType</span> <span class="identifier">failures</span><span class="special">,</span> 244 <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">,</span> 245 <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">)</span> <span class="comment">// (0 <= alpha <= 1), 0.05 equivalent to 95% confidence.</span> 246</pre> 247<p> 248 Returns a <span class="bold"><strong>lower bound</strong></span> on the success fraction: 249 </p> 250<div class="variablelist"> 251<p class="title"><b></b></p> 252<dl class="variablelist"> 253<dt><span class="term">failures</span></dt> 254<dd><p> 255 The total number of failures before the <span class="emphasis"><em>r</em></span>th 256 success. 257 </p></dd> 258<dt><span class="term">successes</span></dt> 259<dd><p> 260 The number of successes required. 261 </p></dd> 262<dt><span class="term">alpha</span></dt> 263<dd><p> 264 The largest acceptable probability that the true value of the success 265 fraction is <span class="bold"><strong>less than</strong></span> the value 266 returned. 267 </p></dd> 268</dl> 269</div> 270<p> 271 For example, if you observe <span class="emphasis"><em>k</em></span> failures and <span class="emphasis"><em>r</em></span> 272 successes from <span class="emphasis"><em>n</em></span> = k + r trials the best estimate 273 for the success fraction is simply <span class="emphasis"><em>r/n</em></span>, but if you 274 want to be 95% sure that the true value is <span class="bold"><strong>greater 275 than</strong></span> some value, <span class="emphasis"><em>p<sub>min</sub></em></span>, then: 276 </p> 277<pre class="programlisting"><span class="identifier">p</span><sub>min</sub> <span class="special">=</span> <span class="identifier">negative_binomial_distribution</span><span class="special"><</span><span class="identifier">RealType</span><span class="special">>::</span><span class="identifier">find_lower_bound_on_p</span><span class="special">(</span> 278 <span class="identifier">failures</span><span class="special">,</span> <span class="identifier">successes</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span> 279</pre> 280<p> 281 <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 282 negative binomial confidence interval example.</a> 283 </p> 284<p> 285 This function uses the Clopper-Pearson method of computing the lower bound 286 on the success fraction, whilst many texts refer to this method as giving 287 an "exact" result in practice it produces an interval that guarantees 288 <span class="emphasis"><em>at least</em></span> the coverage required, and may produce pessimistic 289 estimates for some combinations of <span class="emphasis"><em>failures</em></span> and <span class="emphasis"><em>successes</em></span>. 290 See: 291 </p> 292<p> 293 <a href="http://www.ucs.louisiana.edu/~kxk4695/Discrete_new.pdf" target="_top">Yong 294 Cai and K. Krishnamoorthy, A Simple Improved Inferential Method for Some 295 Discrete Distributions. Computational statistics and data analysis, 2005, 296 vol. 48, no3, 605-621</a>. 297 </p> 298<h6> 299<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h5"></a> 300 <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.upper_bound_on_parameter_p"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.upper_bound_on_parameter_p">Upper 301 Bound on Parameter p</a> 302 </h6> 303<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> 304 <span class="identifier">RealType</span> <span class="identifier">trials</span><span class="special">,</span> 305 <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">,</span> 306 <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">);</span> <span class="comment">// (0 <= alpha <= 1), 0.05 equivalent to 95% confidence.</span> 307</pre> 308<p> 309 Returns an <span class="bold"><strong>upper bound</strong></span> on the success 310 fraction: 311 </p> 312<div class="variablelist"> 313<p class="title"><b></b></p> 314<dl class="variablelist"> 315<dt><span class="term">trials</span></dt> 316<dd><p> 317 The total number of trials conducted. 318 </p></dd> 319<dt><span class="term">successes</span></dt> 320<dd><p> 321 The number of successes that occurred. 322 </p></dd> 323<dt><span class="term">alpha</span></dt> 324<dd><p> 325 The largest acceptable probability that the true value of the success 326 fraction is <span class="bold"><strong>greater than</strong></span> the value 327 returned. 328 </p></dd> 329</dl> 330</div> 331<p> 332 For example, if you observe <span class="emphasis"><em>k</em></span> successes from <span class="emphasis"><em>n</em></span> 333 trials the best estimate for the success fraction is simply <span class="emphasis"><em>k/n</em></span>, 334 but if you want to be 95% sure that the true value is <span class="bold"><strong>less 335 than</strong></span> some value, <span class="emphasis"><em>p<sub>max</sub></em></span>, then: 336 </p> 337<pre class="programlisting"><span class="identifier">p</span><sub>max</sub> <span class="special">=</span> <span class="identifier">negative_binomial_distribution</span><span class="special"><</span><span class="identifier">RealType</span><span class="special">>::</span><span class="identifier">find_upper_bound_on_p</span><span class="special">(</span> 338 <span class="identifier">r</span><span class="special">,</span> <span class="identifier">k</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span> 339</pre> 340<p> 341 <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 342 negative binomial confidence interval example.</a> 343 </p> 344<p> 345 This function uses the Clopper-Pearson method of computing the lower bound 346 on the success fraction, whilst many texts refer to this method as giving 347 an "exact" result in practice it produces an interval that guarantees 348 <span class="emphasis"><em>at least</em></span> the coverage required, and may produce pessimistic 349 estimates for some combinations of <span class="emphasis"><em>failures</em></span> and <span class="emphasis"><em>successes</em></span>. 350 See: 351 </p> 352<p> 353 <a href="http://www.ucs.louisiana.edu/~kxk4695/Discrete_new.pdf" target="_top">Yong 354 Cai and K. Krishnamoorthy, A Simple Improved Inferential Method for Some 355 Discrete Distributions. Computational statistics and data analysis, 2005, 356 vol. 48, no3, 605-621</a>. 357 </p> 358<h6> 359<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h6"></a> 360 <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.estimating_number_of_trials_to_e"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.estimating_number_of_trials_to_e">Estimating 361 Number of Trials to Ensure at Least a Certain Number of Failures</a> 362 </h6> 363<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> 364 <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span> <span class="comment">// number of failures.</span> 365 <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span> <span class="comment">// success fraction.</span> 366 <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> 367</pre> 368<p> 369 This functions estimates the number of trials required to achieve a certain 370 probability that <span class="bold"><strong>more than k failures will be observed</strong></span>. 371 </p> 372<div class="variablelist"> 373<p class="title"><b></b></p> 374<dl class="variablelist"> 375<dt><span class="term">k</span></dt> 376<dd><p> 377 The target number of failures to be observed. 378 </p></dd> 379<dt><span class="term">p</span></dt> 380<dd><p> 381 The probability of <span class="emphasis"><em>success</em></span> for each trial. 382 </p></dd> 383<dt><span class="term">alpha</span></dt> 384<dd><p> 385 The maximum acceptable risk that only k failures or fewer will be 386 observed. 387 </p></dd> 388</dl> 389</div> 390<p> 391 For example: 392 </p> 393<pre class="programlisting"><span class="identifier">negative_binomial_distribution</span><span class="special"><</span><span class="identifier">RealType</span><span class="special">>::</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> 394</pre> 395<p> 396 Returns the smallest number of trials we must conduct to be 95% sure of 397 seeing 10 failures that occur with frequency one half. 398 </p> 399<p> 400 <a class="link" href="../../stat_tut/weg/neg_binom_eg/neg_binom_size_eg.html" title="Estimating Sample Sizes for the Negative Binomial.">Worked 401 Example.</a> 402 </p> 403<p> 404 This function uses numeric inversion of the negative binomial distribution 405 to obtain the result: another interpretation of the result, is that it 406 finds the number of trials (success+failures) that will lead to an <span class="emphasis"><em>alpha</em></span> 407 probability of observing k failures or fewer. 408 </p> 409<h6> 410<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h7"></a> 411 <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.estimating_number_of_trials_to_0"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.estimating_number_of_trials_to_0">Estimating 412 Number of Trials to Ensure a Maximum Number of Failures or Less</a> 413 </h6> 414<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> 415 <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span> <span class="comment">// number of failures.</span> 416 <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span> <span class="comment">// success fraction.</span> 417 <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> 418</pre> 419<p> 420 This functions estimates the maximum number of trials we can conduct and 421 achieve a certain probability that <span class="bold"><strong>k failures or 422 fewer will be observed</strong></span>. 423 </p> 424<div class="variablelist"> 425<p class="title"><b></b></p> 426<dl class="variablelist"> 427<dt><span class="term">k</span></dt> 428<dd><p> 429 The maximum number of failures to be observed. 430 </p></dd> 431<dt><span class="term">p</span></dt> 432<dd><p> 433 The probability of <span class="emphasis"><em>success</em></span> for each trial. 434 </p></dd> 435<dt><span class="term">alpha</span></dt> 436<dd><p> 437 The maximum acceptable <span class="emphasis"><em>risk</em></span> that more than k 438 failures will be observed. 439 </p></dd> 440</dl> 441</div> 442<p> 443 For example: 444 </p> 445<pre class="programlisting"><span class="identifier">negative_binomial_distribution</span><span class="special"><</span><span class="identifier">RealType</span><span class="special">>::</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> 446</pre> 447<p> 448 Returns the largest number of trials we can conduct and still be 95% sure 449 of seeing no failures that occur with frequency one in one million. 450 </p> 451<p> 452 This function uses numeric inversion of the negative binomial distribution 453 to obtain the result: another interpretation of the result, is that it 454 finds the number of trials (success+failures) that will lead to an <span class="emphasis"><em>alpha</em></span> 455 probability of observing more than k failures. 456 </p> 457<h5> 458<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h8"></a> 459 <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.non_member_accessors"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.non_member_accessors">Non-member 460 Accessors</a> 461 </h5> 462<p> 463 All the <a class="link" href="../nmp.html" title="Non-Member Properties">usual non-member accessor 464 functions</a> that are generic to all distributions are supported: 465 <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.cdf">Cumulative Distribution Function</a>, 466 <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.pdf">Probability Density Function</a>, 467 <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>, 468 <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>, 469 <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>, 470 <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.sd">standard deviation</a>, 471 <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>, 472 <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>. 473 </p> 474<p> 475 However it's worth taking a moment to define what these actually mean in 476 the context of this distribution: 477 </p> 478<div class="table"> 479<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.meaning_of_the_non_member_access"></a><p class="title"><b>Table 5.3. Meaning of the non-member accessors.</b></p> 480<div class="table-contents"><table class="table" summary="Meaning of the non-member accessors."> 481<colgroup> 482<col> 483<col> 484</colgroup> 485<thead><tr> 486<th> 487 <p> 488 Function 489 </p> 490 </th> 491<th> 492 <p> 493 Meaning 494 </p> 495 </th> 496</tr></thead> 497<tbody> 498<tr> 499<td> 500 <p> 501 <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.pdf">Probability Density 502 Function</a> 503 </p> 504 </td> 505<td> 506 <p> 507 The probability of obtaining <span class="bold"><strong>exactly k 508 failures</strong></span> from k+r trials with success fraction p. 509 For example: 510 </p> 511<pre class="programlisting"><span class="identifier">pdf</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">k</span><span class="special">)</span></pre> 512 </td> 513</tr> 514<tr> 515<td> 516 <p> 517 <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.cdf">Cumulative Distribution 518 Function</a> 519 </p> 520 </td> 521<td> 522 <p> 523 The probability of obtaining <span class="bold"><strong>k failures 524 or fewer</strong></span> from k+r trials with success fraction p and 525 success on the last trial. For example: 526 </p> 527<pre class="programlisting"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">k</span><span class="special">)</span></pre> 528 </td> 529</tr> 530<tr> 531<td> 532 <p> 533 <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.ccdf">Complement of 534 the Cumulative Distribution Function</a> 535 </p> 536 </td> 537<td> 538 <p> 539 The probability of obtaining <span class="bold"><strong>more than 540 k failures</strong></span> from k+r trials with success fraction p 541 and success on the last trial. For example: 542 </p> 543<pre class="programlisting"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">k</span><span class="special">))</span></pre> 544 </td> 545</tr> 546<tr> 547<td> 548 <p> 549 <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.quantile">Quantile</a> 550 </p> 551 </td> 552<td> 553 <p> 554 The <span class="bold"><strong>greatest</strong></span> number of failures 555 k expected to be observed from k+r trials with success fraction 556 p, at probability P. Note that the value returned is a real-number, 557 and not an integer. Depending on the use case you may want to 558 take either the floor or ceiling of the real result. For example: 559 </p> 560<pre class="programlisting"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">P</span><span class="special">)</span></pre> 561 </td> 562</tr> 563<tr> 564<td> 565 <p> 566 <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.quantile_c">Quantile 567 from the complement of the probability</a> 568 </p> 569 </td> 570<td> 571 <p> 572 The <span class="bold"><strong>smallest</strong></span> number of failures 573 k expected to be observed from k+r trials with success fraction 574 p, at probability P. Note that the value returned is a real-number, 575 and not an integer. Depending on the use case you may want to 576 take either the floor or ceiling of the real result. For example: 577 </p> 578<pre class="programlisting"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">P</span><span class="special">))</span></pre> 579 </td> 580</tr> 581</tbody> 582</table></div> 583</div> 584<br class="table-break"><h5> 585<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h9"></a> 586 <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.accuracy"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.accuracy">Accuracy</a> 587 </h5> 588<p> 589 This distribution is implemented using the incomplete beta functions <a class="link" href="../../sf_beta/ibeta_function.html" title="Incomplete Beta Functions">ibeta</a> and <a class="link" href="../../sf_beta/ibeta_function.html" title="Incomplete Beta Functions">ibetac</a>: 590 please refer to these functions for information on accuracy. 591 </p> 592<h5> 593<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h10"></a> 594 <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.implementation"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.implementation">Implementation</a> 595 </h5> 596<p> 597 In the following table, <span class="emphasis"><em>p</em></span> is the probability that 598 any one trial will be successful (the success fraction), <span class="emphasis"><em>r</em></span> 599 is the number of successes, <span class="emphasis"><em>k</em></span> is the number of failures, 600 <span class="emphasis"><em>p</em></span> is the probability and <span class="emphasis"><em>q = 1-p</em></span>. 601 </p> 602<div class="informaltable"><table class="table"> 603<colgroup> 604<col> 605<col> 606</colgroup> 607<thead><tr> 608<th> 609 <p> 610 Function 611 </p> 612 </th> 613<th> 614 <p> 615 Implementation Notes 616 </p> 617 </th> 618</tr></thead> 619<tbody> 620<tr> 621<td> 622 <p> 623 pdf 624 </p> 625 </td> 626<td> 627 <p> 628 pdf = exp(lgamma(r + k) - lgamma(r) - lgamma(k+1)) * pow(p, r) 629 * pow((1-p), k) 630 </p> 631 <p> 632 Implementation is in terms of <a class="link" href="../../sf_beta/beta_derivative.html" title="Derivative of the Incomplete Beta Function">ibeta_derivative</a>: 633 </p> 634 <p> 635 (p/(r + k)) * ibeta_derivative(r, static_cast<RealType>(k+1), 636 p) The function <a class="link" href="../../sf_beta/beta_derivative.html" title="Derivative of the Incomplete Beta Function">ibeta_derivative</a> 637 is used here, since it has already been optimised for the lowest 638 possible error - indeed this is really just a thin wrapper around 639 part of the internals of the incomplete beta function. 640 </p> 641 </td> 642</tr> 643<tr> 644<td> 645 <p> 646 cdf 647 </p> 648 </td> 649<td> 650 <p> 651 Using the relation: 652 </p> 653 <p> 654 cdf = I<sub>p</sub>(r, k+1) = ibeta(r, k+1, p) 655 </p> 656 <p> 657 = ibeta(r, static_cast<RealType>(k+1), p) 658 </p> 659 </td> 660</tr> 661<tr> 662<td> 663 <p> 664 cdf complement 665 </p> 666 </td> 667<td> 668 <p> 669 Using the relation: 670 </p> 671 <p> 672 1 - cdf = I<sub>p</sub>(k+1, r) 673 </p> 674 <p> 675 = ibetac(r, static_cast<RealType>(k+1), p) 676 </p> 677 </td> 678</tr> 679<tr> 680<td> 681 <p> 682 quantile 683 </p> 684 </td> 685<td> 686 <p> 687 ibeta_invb(r, p, P) - 1 688 </p> 689 </td> 690</tr> 691<tr> 692<td> 693 <p> 694 quantile from the complement 695 </p> 696 </td> 697<td> 698 <p> 699 ibetac_invb(r, p, Q) -1) 700 </p> 701 </td> 702</tr> 703<tr> 704<td> 705 <p> 706 mean 707 </p> 708 </td> 709<td> 710 <p> 711 <code class="computeroutput"><span class="identifier">r</span><span class="special">(</span><span class="number">1</span><span class="special">-</span><span class="identifier">p</span><span class="special">)/</span><span class="identifier">p</span></code> 712 </p> 713 </td> 714</tr> 715<tr> 716<td> 717 <p> 718 variance 719 </p> 720 </td> 721<td> 722 <p> 723 <code class="computeroutput"><span class="identifier">r</span> <span class="special">(</span><span class="number">1</span><span class="special">-</span><span class="identifier">p</span><span class="special">)</span> 724 <span class="special">/</span> <span class="identifier">p</span> 725 <span class="special">*</span> <span class="identifier">p</span></code> 726 </p> 727 </td> 728</tr> 729<tr> 730<td> 731 <p> 732 mode 733 </p> 734 </td> 735<td> 736 <p> 737 <code class="computeroutput"><span class="identifier">floor</span><span class="special">((</span><span class="identifier">r</span><span class="special">-</span><span class="number">1</span><span class="special">)</span> <span class="special">*</span> <span class="special">(</span><span class="number">1</span> <span class="special">-</span> <span class="identifier">p</span><span class="special">)/</span><span class="identifier">p</span><span class="special">)</span></code> 738 </p> 739 </td> 740</tr> 741<tr> 742<td> 743 <p> 744 skewness 745 </p> 746 </td> 747<td> 748 <p> 749 <code class="computeroutput"><span class="special">(</span><span class="number">2</span> 750 <span class="special">-</span> <span class="identifier">p</span><span class="special">)</span> <span class="special">/</span> 751 <span class="identifier">sqrt</span><span class="special">(</span><span class="identifier">r</span> <span class="special">*</span> 752 <span class="special">(</span><span class="number">1</span> 753 <span class="special">-</span> <span class="identifier">p</span><span class="special">))</span></code> 754 </p> 755 </td> 756</tr> 757<tr> 758<td> 759 <p> 760 kurtosis 761 </p> 762 </td> 763<td> 764 <p> 765 <code class="computeroutput"><span class="number">6</span> <span class="special">/</span> 766 <span class="identifier">r</span> <span class="special">+</span> 767 <span class="special">(</span><span class="identifier">p</span> 768 <span class="special">*</span> <span class="identifier">p</span><span class="special">)</span> <span class="special">/</span> 769 <span class="identifier">r</span> <span class="special">*</span> 770 <span class="special">(</span><span class="number">1</span> 771 <span class="special">-</span> <span class="identifier">p</span> 772 <span class="special">)</span></code> 773 </p> 774 </td> 775</tr> 776<tr> 777<td> 778 <p> 779 kurtosis excess 780 </p> 781 </td> 782<td> 783 <p> 784 <code class="computeroutput"><span class="number">6</span> <span class="special">/</span> 785 <span class="identifier">r</span> <span class="special">+</span> 786 <span class="special">(</span><span class="identifier">p</span> 787 <span class="special">*</span> <span class="identifier">p</span><span class="special">)</span> <span class="special">/</span> 788 <span class="identifier">r</span> <span class="special">*</span> 789 <span class="special">(</span><span class="number">1</span> 790 <span class="special">-</span> <span class="identifier">p</span> 791 <span class="special">)</span> <span class="special">-</span><span class="number">3</span></code> 792 </p> 793 </td> 794</tr> 795<tr> 796<td> 797 <p> 798 parameter estimation member functions 799 </p> 800 </td> 801<td> 802 </td> 803</tr> 804<tr> 805<td> 806 <p> 807 <code class="computeroutput"><span class="identifier">find_lower_bound_on_p</span></code> 808 </p> 809 </td> 810<td> 811 <p> 812 ibeta_inv(successes, failures + 1, alpha) 813 </p> 814 </td> 815</tr> 816<tr> 817<td> 818 <p> 819 <code class="computeroutput"><span class="identifier">find_upper_bound_on_p</span></code> 820 </p> 821 </td> 822<td> 823 <p> 824 ibetac_inv(successes, failures, alpha) plus see comments in code. 825 </p> 826 </td> 827</tr> 828<tr> 829<td> 830 <p> 831 <code class="computeroutput"><span class="identifier">find_minimum_number_of_trials</span></code> 832 </p> 833 </td> 834<td> 835 <p> 836 ibeta_inva(k + 1, p, alpha) 837 </p> 838 </td> 839</tr> 840<tr> 841<td> 842 <p> 843 <code class="computeroutput"><span class="identifier">find_maximum_number_of_trials</span></code> 844 </p> 845 </td> 846<td> 847 <p> 848 ibetac_inva(k + 1, p, alpha) 849 </p> 850 </td> 851</tr> 852</tbody> 853</table></div> 854<p> 855 Implementation notes: 856 </p> 857<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 858<li class="listitem"> 859 The real concept type (that deliberately lacks the Lanczos approximation), 860 was found to take several minutes to evaluate some extreme test values, 861 so the test has been disabled for this type. 862 </li> 863<li class="listitem"> 864 Much greater speed, and perhaps greater accuracy, might be achieved 865 for extreme values by using a normal approximation. This is NOT been 866 tested or implemented. 867 </li> 868</ul></div> 869</div> 870<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 871<td align="left"></td> 872<td align="right"><div class="copyright-footer">Copyright © 2006-2019 Nikhar 873 Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, 874 Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan 875 Råde, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, 876 Daryle Walker and Xiaogang Zhang<p> 877 Distributed under the Boost Software License, Version 1.0. (See accompanying 878 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>) 879 </p> 880</div></td> 881</tr></table> 882<hr> 883<div class="spirit-nav"> 884<a accesskey="p" href="lognormal_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="nc_beta_dist.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> 885</div> 886</body> 887</html> 888
