3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
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.11.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">
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>
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>
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>
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 20. 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>
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>
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 20. 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>
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>
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>
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>
73 <span class="special">}}</span> <span class="comment">// namespaces</span>
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".
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.
88 <div class="note"><table border="0" summary="Note">
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>
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.
103 <div class="blockquote"><blockquote class="blockquote"><p>
104 <span class="inlinemediaobject"><img src="../../../../equations/neg_binomial_ref.svg"></span>
106 </p></blockquote></div>
108 The following graph illustrate how the PDF varies as the success fraction
109 <span class="emphasis"><em>p</em></span> changes:
111 <div class="blockquote"><blockquote class="blockquote"><p>
112 <span class="inlinemediaobject"><img src="../../../../graphs/negative_binomial_pdf_1.svg" align="middle"></span>
114 </p></blockquote></div>
116 Alternatively, this graph shows how the shape of the PDF varies as the
117 number of successes changes:
119 <div class="blockquote"><blockquote class="blockquote"><p>
120 <span class="inlinemediaobject"><img src="../../../../graphs/negative_binomial_pdf_2.svg" align="middle"></span>
122 </p></blockquote></div>
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
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
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.
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.
147 For large values of r (successes), the negative binomial distribution converges
148 to the Poisson distribution.
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,
156 The Poisson distribution is a special case for large successes
159 poisson(λ) = lim <sub>r → ∞</sub> negative_binomial(r, r / (λ + r)))
161 <div class="caution"><table border="0" summary="Caution">
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>
166 <tr><td align="left" valign="top">
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.
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.
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.
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
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>
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>
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.
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>.
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>
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>
223 Returns the parameter <span class="emphasis"><em>p</em></span> from which this distribution
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>
229 Returns the parameter <span class="emphasis"><em>r</em></span> from which this distribution
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.
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>
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>
248 Returns a <span class="bold"><strong>lower bound</strong></span> on the success fraction:
250 <div class="variablelist">
251 <p class="title"><b></b></p>
252 <dl class="variablelist">
253 <dt><span class="term">failures</span></dt>
255 The total number of failures before the <span class="emphasis"><em>r</em></span>th
258 <dt><span class="term">successes</span></dt>
260 The number of successes required.
262 <dt><span class="term">alpha</span></dt>
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
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:
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>
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>
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>.
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>.
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>
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>
309 Returns an <span class="bold"><strong>upper bound</strong></span> on the success
312 <div class="variablelist">
313 <p class="title"><b></b></p>
314 <dl class="variablelist">
315 <dt><span class="term">trials</span></dt>
317 The total number of trials conducted.
319 <dt><span class="term">successes</span></dt>
321 The number of successes that occurred.
323 <dt><span class="term">alpha</span></dt>
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
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:
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>
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>
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>.
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>.
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>
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>
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>.
372 <div class="variablelist">
373 <p class="title"><b></b></p>
374 <dl class="variablelist">
375 <dt><span class="term">k</span></dt>
377 The target number of failures to be observed.
379 <dt><span class="term">p</span></dt>
381 The probability of <span class="emphasis"><em>success</em></span> for each trial.
383 <dt><span class="term">alpha</span></dt>
385 The maximum acceptable risk that only k failures or fewer will be
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>
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.
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
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.
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>
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>
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>.
424 <div class="variablelist">
425 <p class="title"><b></b></p>
426 <dl class="variablelist">
427 <dt><span class="term">k</span></dt>
429 The maximum number of failures to be observed.
431 <dt><span class="term">p</span></dt>
433 The probability of <span class="emphasis"><em>success</em></span> for each trial.
435 <dt><span class="term">alpha</span></dt>
437 The maximum acceptable <span class="emphasis"><em>risk</em></span> that more than k
438 failures will be observed.
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>
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.
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.
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
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>.
475 However it's worth taking a moment to define what these actually mean in
476 the context of this distribution:
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.">
501 <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.pdf">Probability Density
507 The probability of obtaining <span class="bold"><strong>exactly k
508 failures</strong></span> from k+r trials with success fraction 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>
517 <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.cdf">Cumulative Distribution
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:
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>
533 <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.ccdf">Complement of
534 the Cumulative Distribution Function</a>
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:
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>
549 <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.quantile">Quantile</a>
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:
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>
566 <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.quantile_c">Quantile
567 from the complement of the probability</a>
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:
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>
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>
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.
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>
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>.
602 <div class="informaltable"><table class="table">
628 pdf = exp(lgamma(r + k) - lgamma(r) - lgamma(k+1)) * pow(p, r)
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>:
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.
654 cdf = I<sub>p</sub>(r, k+1) = ibeta(r, k+1, p)
657 = ibeta(r, static_cast<RealType>(k+1), p)
672 1 - cdf = I<sub>p</sub>(k+1, r)
675 = ibetac(r, static_cast<RealType>(k+1), p)
687 ibeta_invb(r, p, P) - 1
694 quantile from the complement
699 ibetac_invb(r, p, Q) -1)
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>
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>
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>
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>
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>
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>
798 parameter estimation member functions
807 <code class="computeroutput"><span class="identifier">find_lower_bound_on_p</span></code>
812 ibeta_inv(successes, failures + 1, alpha)
819 <code class="computeroutput"><span class="identifier">find_upper_bound_on_p</span></code>
824 ibetac_inv(successes, failures, alpha) plus see comments in code.
831 <code class="computeroutput"><span class="identifier">find_minimum_number_of_trials</span></code>
836 ibeta_inva(k + 1, p, alpha)
843 <code class="computeroutput"><span class="identifier">find_maximum_number_of_trials</span></code>
848 ibetac_inva(k + 1, p, alpha)
855 Implementation notes:
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.
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.
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>)
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>