Imported Upstream version 1.72.0
[platform/upstream/boost.git] / 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.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">
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;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a>   <span class="special">=</span> <a class="link" href="../../pol_ref/pol_ref_ref.html" title="Policy Class Reference">policies::policy&lt;&gt;</a> <span class="special">&gt;</span>
35 <span class="keyword">class</span> <span class="identifier">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;20.&#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 <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(&#955;) = lim <sub>r &#8594; &#8734;</sub> negative_binomial(r, r / (&#955; + 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">&gt;</span>
212           <span class="number">0</span></code> and <code class="computeroutput"><span class="number">0</span>
213           <span class="special">&lt;=</span> <span class="identifier">p</span>
214           <span class="special">&lt;=</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 &lt;= p &lt;= 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 &gt; 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 &lt;= alpha &lt;= 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">&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>
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 &lt;= alpha &lt;= 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">&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>
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">&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>
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">&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>
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&#160;5.3.&#160;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&lt;RealType&gt;(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&lt;RealType&gt;(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&lt;RealType&gt;(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 &#169; 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&#229;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>