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