ceph/src/boost/libs/math/doc/html/math_toolkit/stat_tut/overview/generic.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Generic operations common to all distributions are non-member functions</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="../overview.html" title="Overview of Distributions">
   9 <link rel="prev" href="objects.html" title="Distributions are Objects">
  10 <link rel="next" href="complements.html" title="Complements are supported too - and when to use them">
  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="objects.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.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="complements.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.stat_tut.overview.generic"></a><a class="link" href="generic.html" title="Generic operations common to all distributions are non-member functions">Generic operations
  28         common to all distributions are non-member functions</a>
  29 </h4></div></div></div>
  30 <p>
  31           Want to calculate the PDF (Probability Density Function) of a distribution?
  32           No problem, just use:
  33         </p>
  34 <pre class="programlisting"><span class="identifier">pdf</span><span class="special">(</span><span class="identifier">my_dist</span><span class="special">,</span> <span class="identifier">x</span><span class="special">);</span>  <span class="comment">// Returns PDF (density) at point x of distribution my_dist.</span>
  35 </pre>
  36 <p>
  37           Or how about the CDF (Cumulative Distribution Function):
  38         </p>
  39 <pre class="programlisting"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">my_dist</span><span class="special">,</span> <span class="identifier">x</span><span class="special">);</span>  <span class="comment">// Returns CDF (integral from -infinity to point x)</span>
  40                   <span class="comment">// of distribution my_dist.</span>
  41 </pre>
  42 <p>
  43           And quantiles are just the same:
  44         </p>
  45 <pre class="programlisting"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">my_dist</span><span class="special">,</span> <span class="identifier">p</span><span class="special">);</span>  <span class="comment">// Returns the value of the random variable x</span>
  46                        <span class="comment">// such that cdf(my_dist, x) == p.</span>
  47 </pre>
  48 <p>
  49           If you're wondering why these aren't member functions, it's to make the
  50           library more easily extensible: if you want to add additional generic operations
  51           - let's say the <span class="emphasis"><em>n'th moment</em></span> - then all you have to
  52           do is add the appropriate non-member functions, overloaded for each implemented
  53           distribution type.
  54         </p>
  55 <div class="tip"><table border="0" summary="Tip">
  56 <tr>
  57 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../doc/src/images/tip.png"></td>
  58 <th align="left">Tip</th>
  59 </tr>
  60 <tr><td align="left" valign="top">
  61 <p>
  62             <span class="bold"><strong>Random numbers that approximate Quantiles of Distributions</strong></span>
  63           </p>
  64 <p>
  65             If you want random numbers that are distributed in a specific way, for
  66             example in a uniform, normal or triangular, see <a href="http://www.boost.org/libs/random/" target="_top">Boost.Random</a>.
  67           </p>
  68 <p>
  69             Whilst in principal there's nothing to prevent you from using the quantile
  70             function to convert a uniformly distributed random number to another
  71             distribution, in practice there are much more efficient algorithms available
  72             that are specific to random number generation.
  73           </p>
  74 </td></tr>
  75 </table></div>
  76 <p>
  77           For example, the binomial distribution has two parameters: n (the number
  78           of trials) and p (the probability of success on any one trial).
  79         </p>
  80 <p>
  81           The <code class="computeroutput"><span class="identifier">binomial_distribution</span></code>
  82           constructor therefore has two parameters:
  83         </p>
  84 <p>
  85           <code class="computeroutput"><span class="identifier">binomial_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">RealType</span>
  86           <span class="identifier">p</span><span class="special">);</span></code>
  87         </p>
  88 <p>
  89           For this distribution the <a href="http://en.wikipedia.org/wiki/Random_variate" target="_top">random
  90           variate</a> is k: the number of successes observed. The probability
  91           density/mass function (pdf) is therefore written as <span class="emphasis"><em>f(k; n, p)</em></span>.
  92         </p>
  93 <div class="note"><table border="0" summary="Note">
  94 <tr>
  95 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
  96 <th align="left">Note</th>
  97 </tr>
  98 <tr><td align="left" valign="top">
  99 <p>
 100             <span class="bold"><strong>Random Variates and Distribution Parameters</strong></span>
 101           </p>
 102 <p>
 103             The concept of a <a href="http://en.wikipedia.org/wiki/Random_variable" target="_top">random
 104             variable</a> is closely linked to the term <a href="http://en.wikipedia.org/wiki/Random_variate" target="_top">random
 105             variate</a>: a random variate is a particular value (outcome) of
 106             a random variable. and <a href="http://en.wikipedia.org/wiki/Parameter" target="_top">distribution
 107             parameters</a> are conventionally distinguished (for example in Wikipedia
 108             and Wolfram MathWorld) by placing a semi-colon or vertical bar) <span class="emphasis"><em>after</em></span>
 109             the <a href="http://en.wikipedia.org/wiki/Random_variable" target="_top">random
 110             variable</a> (whose value you 'choose'), to separate the variate
 111             from the parameter(s) that defines the shape of the distribution.<br>
 112             For example, the binomial distribution probability distribution function
 113             (PDF) is written as <span class="emphasis"><em>f(k| n, p)</em></span> = Pr(K = k|n, p)
 114             = probability of observing k successes out of n trials. K is the <a href="http://en.wikipedia.org/wiki/Random_variable" target="_top">random variable</a>,
 115             k is the <a href="http://en.wikipedia.org/wiki/Random_variate" target="_top">random
 116             variate</a>, the parameters are n (trials) and p (probability).
 117           </p>
 118 </td></tr>
 119 </table></div>
 120 <div class="note"><table border="0" summary="Note">
 121 <tr>
 122 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
 123 <th align="left">Note</th>
 124 </tr>
 125 <tr><td align="left" valign="top"><p>
 126             By convention, <a href="http://en.wikipedia.org/wiki/Random_variate" target="_top">random
 127             variate</a> are lower case, usually k is integral, x if real, and
 128             <a href="http://en.wikipedia.org/wiki/Random_variable" target="_top">random variable</a>
 129             are upper case, K if integral, X if real. But this implementation treats
 130             all as floating point values <code class="computeroutput"><span class="identifier">RealType</span></code>,
 131             so if you really want an integral result, you must round: see note on
 132             Discrete Probability Distributions below for details.
 133           </p></td></tr>
 134 </table></div>
 135 <p>
 136           As noted above the non-member function <code class="computeroutput"><span class="identifier">pdf</span></code>
 137           has one parameter for the distribution object, and a second for the random
 138           variate. So taking our binomial distribution example, we would write:
 139         </p>
 140 <p>
 141           <code class="computeroutput"><span class="identifier">pdf</span><span class="special">(</span><span class="identifier">binomial_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;(</span><span class="identifier">n</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">k</span><span class="special">);</span></code>
 142         </p>
 143 <p>
 144           The ranges of <a href="http://en.wikipedia.org/wiki/Random_variate" target="_top">random
 145           variate</a> values that are permitted and are supported can be tested
 146           by using two functions <code class="computeroutput"><span class="identifier">range</span></code>
 147           and <code class="computeroutput"><span class="identifier">support</span></code>.
 148         </p>
 149 <p>
 150           The distribution (effectively the <a href="http://en.wikipedia.org/wiki/Random_variate" target="_top">random
 151           variate</a>) is said to be 'supported' over a range that is <a href="http://en.wikipedia.org/wiki/Probability_distribution" target="_top">"the smallest
 152           closed set whose complement has probability zero"</a>. MathWorld
 153           uses the word 'defined' for this range. Non-mathematicians might say it
 154           means the 'interesting' smallest range of random variate x that has the
 155           cdf going from zero to unity. Outside are uninteresting zones where the
 156           pdf is zero, and the cdf zero or unity.
 157         </p>
 158 <p>
 159           For most distributions, with probability distribution functions one might
 160           describe as 'well-behaved', we have decided that it is most useful for
 161           the supported range to <span class="bold"><strong>exclude</strong></span> random
 162           variate values like exact zero <span class="bold"><strong>if the end point is
 163           discontinuous</strong></span>. For example, the Weibull (scale 1, shape 1) distribution
 164           smoothly heads for unity as the random variate x declines towards zero.
 165           But at x = zero, the value of the pdf is suddenly exactly zero, by definition.
 166           If you are plotting the PDF, or otherwise calculating, zero is not the
 167           most useful value for the lower limit of supported, as we discovered. So
 168           for this, and similar distributions, we have decided it is most numerically
 169           useful to use the closest value to zero, min_value, for the limit of the
 170           supported range. (The <code class="computeroutput"><span class="identifier">range</span></code>
 171           remains from zero, so you will still get <code class="computeroutput"><span class="identifier">pdf</span><span class="special">(</span><span class="identifier">weibull</span><span class="special">,</span> <span class="number">0</span><span class="special">)</span>
 172           <span class="special">==</span> <span class="number">0</span></code>).
 173           (Exponential and gamma distributions have similarly discontinuous functions).
 174         </p>
 175 <p>
 176           Mathematically, the functions may make sense with an (+ or -) infinite
 177           value, but except for a few special cases (in the Normal and Cauchy distributions)
 178           this implementation limits random variates to finite values from the <code class="computeroutput"><span class="identifier">max</span></code> to <code class="computeroutput"><span class="identifier">min</span></code>
 179           for the <code class="computeroutput"><span class="identifier">RealType</span></code>. (See
 180           <a class="link" href="../../sf_implementation.html#math_toolkit.sf_implementation.handling_of_floating_point_infin">Handling
 181           of Floating-Point Infinity</a> for rationale).
 182         </p>
 183 <div class="note"><table border="0" summary="Note">
 184 <tr>
 185 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
 186 <th align="left">Note</th>
 187 </tr>
 188 <tr><td align="left" valign="top">
 189 <p>
 190             <span class="bold"><strong>Discrete Probability Distributions</strong></span>
 191           </p>
 192 <p>
 193             Note that the <a href="http://en.wikipedia.org/wiki/Discrete_probability_distribution" target="_top">discrete
 194             distributions</a>, including the binomial, negative binomial, Poisson
 195             &amp; Bernoulli, are all mathematically defined as discrete functions:
 196             that is to say the functions <code class="computeroutput"><span class="identifier">cdf</span></code>
 197             and <code class="computeroutput"><span class="identifier">pdf</span></code> are only defined
 198             for integral values of the random variate.
 199           </p>
 200 <p>
 201             However, because the method of calculation often uses continuous functions
 202             it is convenient to treat them as if they were continuous functions,
 203             and permit non-integral values of their parameters.
 204           </p>
 205 <p>
 206             Users wanting to enforce a strict mathematical model may use <code class="computeroutput"><span class="identifier">floor</span></code> or <code class="computeroutput"><span class="identifier">ceil</span></code>
 207             functions on the random variate prior to calling the distribution function.
 208           </p>
 209 <p>
 210             The quantile functions for these distributions are hard to specify in
 211             a manner that will satisfy everyone all of the time. The default behaviour
 212             is to return an integer result, that has been rounded <span class="emphasis"><em>outwards</em></span>:
 213             that is to say, lower quantiles - where the probablity is less than 0.5
 214             are rounded down, while upper quantiles - where the probability is greater
 215             than 0.5 - are rounded up. This behaviour ensures that if an X% quantile
 216             is requested, then <span class="emphasis"><em>at least</em></span> the requested coverage
 217             will be present in the central region, and <span class="emphasis"><em>no more than</em></span>
 218             the requested coverage will be present in the tails.
 219           </p>
 220 <p>
 221             This behaviour can be changed so that the quantile functions are rounded
 222             differently, or return a real-valued result using <a class="link" href="../../pol_overview.html" title="Policy Overview">Policies</a>.
 223             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
 224             Quantiles of Discrete Distributions</a> before using the quantile
 225             function on a discrete distribtion. The <a class="link" href="../../pol_ref/discrete_quant_ref.html" title="Discrete Quantile Policies">reference
 226             docs</a> describe how to change the rounding policy for these distributions.
 227           </p>
 228 <p>
 229             For similar reasons continuous distributions with parameters like "degrees
 230             of freedom" that might appear to be integral, are treated as real
 231             values (and are promoted from integer to floating-point if necessary).
 232             In this case however, there are a small number of situations where non-integral
 233             degrees of freedom do have a genuine meaning.
 234           </p>
 235 </td></tr>
 236 </table></div>
 237 </div>
 238 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 239 <td align="left"></td>
 240 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2010, 2012-2014 Nikhar Agrawal,
 241       Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
 242       Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Johan R&#229;de, Gautam Sewani,
 243       Benjamin Sobotta, Thijs van den Berg, Daryle Walker and Xiaogang Zhang<p>
 244         Distributed under the Boost Software License, Version 1.0. (See accompanying
 245         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>)
 246       </p>
 247 </div></td>
 248 </tr></table>
 249 <hr>
 250 <div class="spirit-nav">
 251 <a accesskey="p" href="objects.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.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="complements.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 252 </div>
 253 </body>
 254 </html>