| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> |
| <title>Generic operations common to all distributions are non-member functions</title> |
| <link rel="stylesheet" href="../../../math.css" type="text/css"> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.77.1"> |
| <link rel="home" href="../../../index.html" title="Math Toolkit 2.2.0"> |
| <link rel="up" href="../overview.html" title="Overview of Distributions"> |
| <link rel="prev" href="objects.html" title="Distributions are Objects"> |
| <link rel="next" href="complements.html" title="Complements are supported too - and when to use them"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table cellpadding="2" width="100%"><tr> |
| <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td> |
| <td align="center"><a href="../../../../../../../index.html">Home</a></td> |
| <td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td> |
| <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> |
| <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> |
| <td align="center"><a href="../../../../../../../more/index.htm">More</a></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <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> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <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 |
| common to all distributions are non-member functions</a> |
| </h4></div></div></div> |
| <p> |
| Want to calculate the PDF (Probability Density Function) of a distribution? |
| No problem, just use: |
| </p> |
| <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> |
| </pre> |
| <p> |
| Or how about the CDF (Cumulative Distribution Function): |
| </p> |
| <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> |
| <span class="comment">// of distribution my_dist.</span> |
| </pre> |
| <p> |
| And quantiles are just the same: |
| </p> |
| <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> |
| <span class="comment">// such that cdf(my_dist, x) == p.</span> |
| </pre> |
| <p> |
| If you're wondering why these aren't member functions, it's to make the |
| library more easily extensible: if you want to add additional generic operations |
| - let's say the <span class="emphasis"><em>n'th moment</em></span> - then all you have to |
| do is add the appropriate non-member functions, overloaded for each implemented |
| distribution type. |
| </p> |
| <div class="tip"><table border="0" summary="Tip"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../doc/src/images/tip.png"></td> |
| <th align="left">Tip</th> |
| </tr> |
| <tr><td align="left" valign="top"> |
| <p> |
| <span class="bold"><strong>Random numbers that approximate Quantiles of Distributions</strong></span> |
| </p> |
| <p> |
| If you want random numbers that are distributed in a specific way, for |
| example in a uniform, normal or triangular, see <a href="http://www.boost.org/libs/random/" target="_top">Boost.Random</a>. |
| </p> |
| <p> |
| Whilst in principal there's nothing to prevent you from using the quantile |
| function to convert a uniformly distributed random number to another |
| distribution, in practice there are much more efficient algorithms available |
| that are specific to random number generation. |
| </p> |
| </td></tr> |
| </table></div> |
| <p> |
| For example, the binomial distribution has two parameters: n (the number |
| of trials) and p (the probability of success on any one trial). |
| </p> |
| <p> |
| The <code class="computeroutput"><span class="identifier">binomial_distribution</span></code> |
| constructor therefore has two parameters: |
| </p> |
| <p> |
| <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> |
| <span class="identifier">p</span><span class="special">);</span></code> |
| </p> |
| <p> |
| For this distribution the <a href="http://en.wikipedia.org/wiki/Random_variate" target="_top">random |
| variate</a> is k: the number of successes observed. The probability |
| density/mass function (pdf) is therefore written as <span class="emphasis"><em>f(k; n, p)</em></span>. |
| </p> |
| <div class="note"><table border="0" summary="Note"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td> |
| <th align="left">Note</th> |
| </tr> |
| <tr><td align="left" valign="top"> |
| <p> |
| <span class="bold"><strong>Random Variates and Distribution Parameters</strong></span> |
| </p> |
| <p> |
| The concept of a <a href="http://en.wikipedia.org/wiki/Random_variable" target="_top">random |
| variable</a> is closely linked to the term <a href="http://en.wikipedia.org/wiki/Random_variate" target="_top">random |
| variate</a>: a random variate is a particular value (outcome) of |
| a random variable. and <a href="http://en.wikipedia.org/wiki/Parameter" target="_top">distribution |
| parameters</a> are conventionally distinguished (for example in Wikipedia |
| and Wolfram MathWorld) by placing a semi-colon or vertical bar) <span class="emphasis"><em>after</em></span> |
| the <a href="http://en.wikipedia.org/wiki/Random_variable" target="_top">random |
| variable</a> (whose value you 'choose'), to separate the variate |
| from the parameter(s) that defines the shape of the distribution.<br> |
| For example, the binomial distribution probability distribution function |
| (PDF) is written as <span class="emphasis"><em>f(k| n, p)</em></span> = Pr(K = k|n, p) |
| = 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>, |
| k is the <a href="http://en.wikipedia.org/wiki/Random_variate" target="_top">random |
| variate</a>, the parameters are n (trials) and p (probability). |
| </p> |
| </td></tr> |
| </table></div> |
| <div class="note"><table border="0" summary="Note"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td> |
| <th align="left">Note</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| By convention, <a href="http://en.wikipedia.org/wiki/Random_variate" target="_top">random |
| variate</a> are lower case, usually k is integral, x if real, and |
| <a href="http://en.wikipedia.org/wiki/Random_variable" target="_top">random variable</a> |
| are upper case, K if integral, X if real. But this implementation treats |
| all as floating point values <code class="computeroutput"><span class="identifier">RealType</span></code>, |
| so if you really want an integral result, you must round: see note on |
| Discrete Probability Distributions below for details. |
| </p></td></tr> |
| </table></div> |
| <p> |
| As noted above the non-member function <code class="computeroutput"><span class="identifier">pdf</span></code> |
| has one parameter for the distribution object, and a second for the random |
| variate. So taking our binomial distribution example, we would write: |
| </p> |
| <p> |
| <code class="computeroutput"><span class="identifier">pdf</span><span class="special">(</span><span class="identifier">binomial_distribution</span><span class="special"><</span><span class="identifier">RealType</span><span class="special">>(</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> |
| </p> |
| <p> |
| The ranges of <a href="http://en.wikipedia.org/wiki/Random_variate" target="_top">random |
| variate</a> values that are permitted and are supported can be tested |
| by using two functions <code class="computeroutput"><span class="identifier">range</span></code> |
| and <code class="computeroutput"><span class="identifier">support</span></code>. |
| </p> |
| <p> |
| The distribution (effectively the <a href="http://en.wikipedia.org/wiki/Random_variate" target="_top">random |
| 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 |
| closed set whose complement has probability zero"</a>. MathWorld |
| uses the word 'defined' for this range. Non-mathematicians might say it |
| means the 'interesting' smallest range of random variate x that has the |
| cdf going from zero to unity. Outside are uninteresting zones where the |
| pdf is zero, and the cdf zero or unity. |
| </p> |
| <p> |
| For most distributions, with probability distribution functions one might |
| describe as 'well-behaved', we have decided that it is most useful for |
| the supported range to <span class="bold"><strong>exclude</strong></span> random |
| variate values like exact zero <span class="bold"><strong>if the end point is |
| discontinuous</strong></span>. For example, the Weibull (scale 1, shape 1) distribution |
| smoothly heads for unity as the random variate x declines towards zero. |
| But at x = zero, the value of the pdf is suddenly exactly zero, by definition. |
| If you are plotting the PDF, or otherwise calculating, zero is not the |
| most useful value for the lower limit of supported, as we discovered. So |
| for this, and similar distributions, we have decided it is most numerically |
| useful to use the closest value to zero, min_value, for the limit of the |
| supported range. (The <code class="computeroutput"><span class="identifier">range</span></code> |
| 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> |
| <span class="special">==</span> <span class="number">0</span></code>). |
| (Exponential and gamma distributions have similarly discontinuous functions). |
| </p> |
| <p> |
| Mathematically, the functions may make sense with an (+ or -) infinite |
| value, but except for a few special cases (in the Normal and Cauchy distributions) |
| 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> |
| for the <code class="computeroutput"><span class="identifier">RealType</span></code>. (See |
| <a class="link" href="../../sf_implementation.html#math_toolkit.sf_implementation.handling_of_floating_point_infin">Handling |
| of Floating-Point Infinity</a> for rationale). |
| </p> |
| <div class="note"><table border="0" summary="Note"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td> |
| <th align="left">Note</th> |
| </tr> |
| <tr><td align="left" valign="top"> |
| <p> |
| <span class="bold"><strong>Discrete Probability Distributions</strong></span> |
| </p> |
| <p> |
| Note that the <a href="http://en.wikipedia.org/wiki/Discrete_probability_distribution" target="_top">discrete |
| distributions</a>, including the binomial, negative binomial, Poisson |
| & Bernoulli, are all mathematically defined as discrete functions: |
| that is to say the functions <code class="computeroutput"><span class="identifier">cdf</span></code> |
| and <code class="computeroutput"><span class="identifier">pdf</span></code> are only defined |
| for integral values of the random variate. |
| </p> |
| <p> |
| However, because the method of calculation often uses continuous functions |
| it is convenient to treat them as if they were continuous functions, |
| and permit non-integral values of their parameters. |
| </p> |
| <p> |
| 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> |
| functions on the random variate prior to calling the distribution function. |
| </p> |
| <p> |
| The quantile functions for these distributions are hard to specify in |
| a manner that will satisfy everyone all of the time. The default behaviour |
| is to return an integer result, that has been rounded <span class="emphasis"><em>outwards</em></span>: |
| that is to say, lower quantiles - where the probablity is less than 0.5 |
| are rounded down, while upper quantiles - where the probability is greater |
| than 0.5 - are rounded up. This behaviour ensures that if an X% quantile |
| is requested, then <span class="emphasis"><em>at least</em></span> the requested coverage |
| will be present in the central region, and <span class="emphasis"><em>no more than</em></span> |
| the requested coverage will be present in the tails. |
| </p> |
| <p> |
| This behaviour can be changed so that the quantile functions are rounded |
| differently, or return a real-valued result using <a class="link" href="../../pol_overview.html" title="Policy Overview">Policies</a>. |
| 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 |
| Quantiles of Discrete Distributions</a> before using the quantile |
| function on a discrete distribtion. The <a class="link" href="../../pol_ref/discrete_quant_ref.html" title="Discrete Quantile Policies">reference |
| docs</a> describe how to change the rounding policy for these distributions. |
| </p> |
| <p> |
| For similar reasons continuous distributions with parameters like "degrees |
| of freedom" that might appear to be integral, are treated as real |
| values (and are promoted from integer to floating-point if necessary). |
| In this case however, there are a small number of situations where non-integral |
| degrees of freedom do have a genuine meaning. |
| </p> |
| </td></tr> |
| </table></div> |
| </div> |
| <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> |
| <td align="left"></td> |
| <td align="right"><div class="copyright-footer">Copyright © 2006-2010, 2012-2014 Nikhar Agrawal, |
| Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert |
| Holin, Bruno Lalande, John Maddock, Johan Råde, Gautam Sewani, Benjamin Sobotta, |
| Thijs van den Berg, Daryle Walker and Xiaogang Zhang<p> |
| Distributed under the Boost Software License, Version 1.0. (See accompanying |
| 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>) |
| </p> |
| </div></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <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> |
| </div> |
| </body> |
| </html> |