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