dist_tutorial.qbk

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

it is convenient to treat them as if they were continuous functions,
and permit non-integral values of their parameters.

Users wanting to enforce a strict mathematical model may use `floor` 
or `ceil` functions on the random variate prior to calling the distribution 
function.

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 
/outwards/: 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 /at least/ the requested
coverage will be present in the central region, and /no more than/
the requested coverage will be present in the tails.

This behaviour can be changed so that the quantile functions are rounded
differently, or return a real-valued result using 
[link math_toolkit.policy.pol_overview Policies].  It is strongly
recommended that you read the tutorial 
[link math_toolkit.policy.pol_tutorial.understand_dis_quant
Understanding Quantiles of Discrete Distributions] before
using the quantile function on a discrete distribtion.  The
[link math_toolkit.policy.pol_ref.discrete_quant_ref reference docs] 
describe how to change the rounding policy
for these distributions.

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.
]

[#complements]
[h4 Complements are supported too]

Often you don't want the value of the CDF, but its complement, which is
to say `1-p` rather than `p`.  You could calculate the CDF and subtract
it from `1`, but if `p` is very close to `1` then cancellation error
will cause you to lose significant digits.  In extreme cases, `p` may
actually be equal to `1`, even though the true value of the complement is non-zero.

[link why_complements See also ['"Why complements?"]]

In this library, whenever you want to receive a complement, just wrap
all the function arguments in a call to `complement(...)`, for example:

   students_t dist(5);
   cout << "CDF at t = 1 is " << cdf(dist, 1.0) << endl;
   cout << "Complement of CDF at t = 1 is " << cdf(complement(dist, 1.0)) << endl;

But wait, now that we have a complement, we have to be able to use it as well.
Any function that accepts a probability as an argument can also accept a complement
by wrapping all of its arguments in a call to `complement(...)`, for example:

   students_t dist(5);
   
   for(double i = 10; i < 1e10; i *= 10)
   {
      // Calculate the quantile for a 1 in i chance:
      double t = quantile(complement(dist, 1/i));
      // Print it out:
      cout << "Quantile of students-t with 5 degrees of freedom\n"
              "for a 1 in " << i << " chance is " << t << endl;
   }
 
[tip

[*Critical values are just quantiles]

Some texts talk about quantiles, others about critical values, the basic rule is:

['Lower critical values] are the same as the quantile.

['Upper critical values] are the same as the quantile from the complement
of the probability.

For example, suppose we have a Bernoulli process, giving rise to a binomial
distribution with success ratio 0.1 and 100 trials in total.  The 
['lower critical value] for a probability of 0.05 is given by:

`quantile(binomial(100, 0.1), 0.05)`

and the ['upper critical value] is given by:

`quantile(complement(binomial(100, 0.1), 0.05))`

which return 4.82 and 14.63 respectively.
]

[#why_complements]
[tip

[*Why bother with complements anyway?]

It's very tempting to dispense with complements, and simply subtract
the probability from 1 when required.  However, consider what happens when
the probability is very close to 1: let's say the probability expressed at
float precision is `0.999999940f`, then `1 - 0.999999940f = 5.96046448e-008`,
but the result is actually accurate to just ['one single bit]: the only
bit that didn't cancel out!

Or to look at this another way: consider that we want the risk of falsely
rejecting the null-hypothesis in the Student's t test to be 1 in 1 billion,
for a sample size of 10,000.
This gives a probability of 1 - 10[super -9], which is exactly 1 when 
calculated at float precision.  In this case calculating the quantile from
the complement neatly solves the problem, so for example:

`quantile(complement(students_t(10000), 1e-9))`

returns the expected t-statistic `6.00336`, where as:

`quantile(students_t(10000), 1-1e-9f)`

raises an overflow error, since it is the same as:

`quantile(students_t(10000), 1)`

Which has no finite result.
]

[h4 Parameters can be calculated]

Sometimes it's the parameters that define the distribution that you 
need to find.  Suppose, for example, you have conducted a Students-t test
for equal means and the result is borderline.  Maybe your two samples
differ from each other, or maybe they don't; based on the result
of the test you can't be sure.  A legitimate question to ask then is
"How many more measurements would I have to take before I would get
an X% probability that the difference is real?"  Parameter finders
can answer questions like this, and are necessarily different for
each distribution.  They are implemented as static member functions
of the distributions, for example:

   students_t::find_degrees_of_freedom(
      1.3,        // difference from true mean to detect
      0.05,       // maximum risk of falsely rejecting the null-hypothesis.
      0.1,        // maximum risk of falsely failing to reject the null-hypothesis.
      0.13);      // sample standard deviation
      
Returns the number of degrees of freedom required to obtain a 95%
probability that the observed differences in means is not down to
chance alone.  In the case that a borderline Students-t test result
was previously obtained, this can be used to estimate how large the sample size
would have to become before the observed difference was considered
significant.  It assumes, of course, that the sample mean and standard
deviation are invariant with sample size.
   
[h4 Summary]

* Distributions are objects, which are constructed from whatever
parameters the distribution may have.
* Member functions allow you to retrieve the parameters of a distribution.
* Generic non-member functions provide access to the properties that
are common to all the distributions (PDF, CDF, quantile etc).
* Complements of probabilities are calculated by wrapping the function's
arguments in a call to `complement(...)`.
* Functions that accept a probability can accept a complement of the
probability as well, by wrapping the function's
arguments in a call to `complement(...)`.
* Static member functions allow the parameters of a distribution
to be found from other information.

Now that you have the basics, the next section looks at some worked examples.

[endsect] [/section:overview Overview]

[section:weg Worked Examples]
[include distributions/distribution_construction.qbk]
[include distributions/students_t_examples.qbk]
[include distributions/chi_squared_examples.qbk]
[include distributions/f_dist_example.qbk]
[include distributions/binomial_example.qbk]
[include distributions/negative_binomial_example.qbk]
[include distributions/normal_example.qbk]
[include distributions/nc_chi_squared_example.qbk]
[include distributions/error_handling_example.qbk]
[include distributions/find_location_and_scale.qbk]
[include distributions/nag_library.qbk]
[endsect] [/section:weg Worked Examples]

[include background.qbk]

[endsect] [/ section:stat_tut Statistical Distributions Tutorial]

[/ dist_tutorial.qbk
  Copyright 2006 John Maddock and Paul A. Bristow.
  Distributed under the Boost Software License, Version 1.0.
  (See accompanying file LICENSE_1_0.txt or copy at
  http://www.boost.org/LICENSE_1_0.txt).
]