dist_tutorial.qbk

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

[/ def names end in distrib to avoid clashes]
[def __binomial_distrib [link math_toolkit.dist.dist_ref.dists.binomial_dist Binomial Distribution]]
[def __chi_squared_distrib [link math_toolkit.dist.dist_ref.dists.chi_squared_dist Chi Squared Distribution]]
[def __normal_distrib [link math_toolkit.dist.dist_ref.dists.normal_dist Normal Distribution]]
[def __F_distrib [link math_toolkit.dist.dist_ref.dists.f_dist Fisher F Distribution]]
[def __students_t_distrib [link math_toolkit.dist.dist_ref.dists.students_t_dist Students t Distribution]]

[def __handbook [@http://www.itl.nist.gov/div898/handbook/ 
NIST/SEMATECH e-Handbook of Statistical Methods.]]

[section:stat_tut Statistical Distributions Tutorial]
This library is centred around statistical distributions, this tutorial
will give you an overview of what they are, how they can be used, and 
provides a few worked examples of applying the library to statistical tests.

[section:overview Overview]

[h4 Headers and Namespaces]

All the code in this library is inside namespace boost::math.

In order to use a distribution /my_distribution/ you will need to include
either the header <boost/math/distributions/my_distribution.hpp> or
the "include everything" header: <boost/math/distributions.hpp>.

For example, to use the Students-t distribution include either
<boost/math/distributions/students_t.hpp> or
<boost/math/distributions.hpp>

[h4 Distributions are Objects]

Each kind of distribution in this library is a class type.

[link math_toolkit.policy Policies] provide fine-grained control 
of the behaviour of these classes, allowing the user to customise
behaviour such as how errors are handled, or how the quantiles
of discrete distribtions behave.

[tip If you are familiar with statistics libraries using functions,
and 'Distributions as Objects' seem alien, see
[link math_toolkit.dist.stat_tut.weg.nag_library the comparison to 
other statistics libraries.]  
] [/tip]

Making distributions class types does two things:

* It encapsulates the kind of distribution in the C++ type system; 
so, for example, Students-t distributions are always a different C++ type from 
Chi-Squared distributions.
* The distribution objects store any parameters associated with the 
distribution: for example, the Students-t distribution has a
['degrees of freedom] parameter that controls the shape of the distribution.
This ['degrees of freedom] parameter has to be provided
to the Students-t object when it is constructed.

Although the distribution classes in this library are templates, there
are typedefs on type /double/ that mostly take the usual name of the
distribution
(except where there is a clash with a function of the same name: beta and gamma,
in which case using the default template arguments - `RealType = double` - 
is nearly as convenient).
Probably 95% of uses are covered by these typedefs:

   using namespace boost::math;
   
   // Construct a students_t distribution with 4 degrees of freedom:
   students_t d1(4);
   
   // Construct a double-precision beta distribution 
   // with parameters a = 10, b = 20
   beta_distribution<> d2(10, 20); // Note: _distribution<> suffix !
   
If you need to use the distributions with a type other than `double`,
then you can instantiate the template directly: the names of the 
templates are the same as the `double` typedef but with `_distribution`
appended, for example: __students_t_distrib or __binomial_distrib:

   // Construct a students_t distribution, of float type,
   // with 4 degrees of freedom:
   students_t_distribution<float> d3(4);
   
   // Construct a binomial distribution, of long double type,
   // with probability of success 0.3
   // and 20 trials in total:
   binomial_distribution<long double> d4(20, 0.3);
   
The parameters passed to the distributions can be accessed via getter member
functions:

   d1.degrees_of_freedom();  // returns 4.0 
   
This is all well and good, but not very useful so far.  What we often want
is to be able to calculate the /cumulative distribution functions/ and
/quantiles/ etc for these distributions.

[h4 Generic operations common to all distributions are non-member functions]

Want to calculate the PDF (Probability Density Function) of a distribution?
No problem, just use:

   pdf(my_dist, x);  // Returns PDF (density) at point x of distribution my_dist.
   
Or how about the CDF (Cumulative Distribution Function):

   cdf(my_dist, x);  // Returns CDF (integral from -infinity to point x)
                     // of distribution my_dist.
   
And quantiles are just the same:

   quantile(my_dist, p);  // Returns the value of the random variable x
                          // such that cdf(my_dist, x) == 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 /n'th moment/ - then all you have to
do is add the appropriate non-member functions, overloaded for each
implemented distribution type.

[tip

[*Random numbers that approximate Quantiles of Distributions]

If you want random numbers that are distributed in a specific way,
for example in a uniform, normal or triangular,
see [@http://www.boost.org/libs/random/ Boost.Random].

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.
] [/tip Random numbers that approximate Quantiles of Distributions]

For example, the binomial distribution has two parameters:
n (the number of trials) and p (the probability of success on one trial).

The `binomial_distribution` constructor therefore has two parameters:

`binomial_distribution(RealType n, RealType p);`
  
For this distribution the random variate is k: the number of successes observed.
The probability density\/mass function (pdf) is therefore written as ['f(k; n, p)].

[note

[*Random Variates and Distribution Parameters]

[@http://en.wikipedia.org/wiki/Random_variate Random variates]
and [@http://en.wikipedia.org/wiki/Parameter distribution parameters]
are conventionally distinguished (for example in Wikipedia and Wolfram MathWorld
by placing a semi-colon (or sometimes vertical bar)
after the random variate (whose value you 'choose'),
to separate the variate from the parameter(s) that defines the shape of the distribution.
] [/tip Random Variates and Distribution Parameters]

As noted above the non-member function `pdf` has one parameter for the distribution object,
and a second for the random variate.  So taking our binomial distribution 
example, we would write:

`pdf(binomial_distribution<RealType>(n, p), k);`

The ranges of random variate values that are permitted and are supported can be 
tested by using two functions `range` and `support`.

The distribution (effectively the random variate) is said to be 'supported' 
over a range that is
[@http://en.wikipedia.org/wiki/Probability_distribution
 "the smallest closed set whose complement has probability zero"].
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.

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 exclude random variate values like exact zero *if the end point is discontinuous*.
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 `range` remains from zero, so you will still get `pdf(weibull, 0) == 0`).
(Exponential and gamma distributions have similarly discontinuous functions).

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 `max` 
to `min` for the `RealType`.
(See [link math_toolkit.backgrounders.implementation.handling_of_floating_point_infinity 
Handling of Floating-Point Infinity] for rationale).


[note

[*Discrete Probability Distributions]

Note that the [@http://en.wikipedia.org/wiki/Discrete_probability_distribution 
discrete distributions], including the binomial, negative binomial, Poisson & Bernoulli,
are all mathematically defined as discrete functions:
that is to say the functions `cdf` and `pdf` are only defined for integral values 
of the random variate.

However, because the method of calculation often uses continuous functions