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