Squashed 'third_party/boostorg/math/' content from commit 0e9549f
Change-Id: I7c2a13cb6a5beea4a471341510d8364cedd71613
git-subtree-dir: third_party/boostorg/math
git-subtree-split: 0e9549ff2f854e6edafaf4627d65026f2f533a18
diff --git a/doc/distributions/arcsine.qbk b/doc/distributions/arcsine.qbk
new file mode 100644
index 0000000..8dc731e
--- /dev/null
+++ b/doc/distributions/arcsine.qbk
@@ -0,0 +1,288 @@
+[section:arcine_dist Arcsine Distribution]
+
+[import ../../example/arcsine_example.cpp] [/ for arcsine snips below]
+
+
+``#include <boost/math/distributions/arcsine.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class arcsine_distribution;
+
+ typedef arcsine_distribution<double> arcsine; // double precision standard arcsine distribution [0,1].
+
+ template <class RealType, class ``__Policy``>
+ class arcsine_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ // Constructor from two range parameters, x_min and x_max:
+ arcsine_distribution(RealType x_min, RealType x_max);
+
+ // Range Parameter accessors:
+ RealType x_min() const;
+ RealType x_max() const;
+ };
+ }} // namespaces
+
+The class type `arcsine_distribution` represents an
+[@http://en.wikipedia.org/wiki/arcsine_distribution arcsine]
+[@http://en.wikipedia.org/wiki/Probability_distribution probability distribution function].
+The arcsine distribution is named because its CDF uses the inverse sin[super -1] or arcsine.
+
+This is implemented as a generalized version with support from ['x_min] to ['x_max]
+providing the 'standard arcsine distribution' as default with ['x_min = 0] and ['x_max = 1].
+(A few make other choices for 'standard').
+
+The arcsine distribution is generalized to include any bounded support ['a <= x <= b] by
+[@http://reference.wolfram.com/language/ref/ArcSinDistribution.html Wolfram] and
+[@http://en.wikipedia.org/wiki/arcsine_distribution Wikipedia],
+but also using ['location] and ['scale] parameters by
+[@http://www.math.uah.edu/stat/index.html Virtual Laboratories in Probability and Statistics]
+[@http://www.math.uah.edu/stat/special/Arcsine.html Arcsine distribution].
+The end-point version is simpler and more obvious, so we implement that.
+If desired, [@http://en.wikipedia.org/wiki/arcsine_distribution this]
+outlines how the __beta_distrib can be used to add a shape factor.
+
+The [@http://en.wikipedia.org/wiki/Probability_density_function probability density function PDF]
+for the [@http://en.wikipedia.org/wiki/arcsine_distribution arcsine distribution]
+defined on the interval \[['x_min, x_max]\] is given by:
+
+[figspace] [figspace] f(x; x_min, x_max) = 1 /([pi][sdot][sqrt]((x - x_min)[sdot](x_max - x_min))
+
+For example, __WolframAlpha arcsine distribution, from input of
+
+ N[PDF[arcsinedistribution[0, 1], 0.5], 50]
+
+computes the PDF value
+
+ 0.63661977236758134307553505349005744813783858296183
+
+The Probability Density Functions (PDF) of generalized arcsine distributions are symmetric U-shaped curves,
+centered on ['(x_max - x_min)/2],
+highest (infinite) near the two extrema, and quite flat over the central region.
+
+If random variate ['x] is ['x_min] or ['x_max], then the PDF is infinity.
+If random variate ['x] is ['x_min] then the CDF is zero.
+If random variate ['x] is ['x_max] then the CDF is unity.
+
+The 'Standard' (0, 1) arcsine distribution is shown in blue
+and some generalized examples with other ['x] ranges.
+
+[graph arcsine_pdf]
+
+The Cumulative Distribution Function CDF is defined as
+
+[figspace] [figspace] F(x) = 2[sdot]arcsin([sqrt]((x-x_min)/(x_max - x))) / [pi]
+
+[graph arcsine_cdf]
+
+[h5 Constructor]
+
+ arcsine_distribution(RealType x_min, RealType x_max);
+
+constructs an arcsine distribution with range parameters ['x_min] and ['x_max].
+
+Requires ['x_min < x_max], otherwise __domain_error is called.
+
+For example:
+
+ arcsine_distribution<> myarcsine(-2, 4);
+
+constructs an arcsine distribution with ['x_min = -2] and ['x_max = 4].
+
+Default values of ['x_min = 0] and ['x_max = 1] and a ` typedef arcsine_distribution<double> arcsine;` mean that
+
+ arcsine as;
+
+constructs a 'Standard 01' arcsine distribution.
+
+[h5 Parameter Accessors]
+
+ RealType x_min() const;
+ RealType x_max() const;
+
+Return the parameter ['x_min] or ['x_max] from which this distribution was constructed.
+
+So, for example:
+
+[arcsine_snip_8]
+
+[h4 Non-member Accessor Functions]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
+that are generic to all distributions are supported: __usual_accessors.
+
+The formulae for calculating these are shown in the table below, and at
+[@http://mathworld.wolfram.com/arcsineDistribution.html Wolfram Mathworld].
+
+[note There are always [*two] values for the [*mode], at ['x_min] and at ['x_max], default 0 and 1,
+so instead we raise the exception __domain_error.
+At these extrema, the PDFs are infinite, and the CDFs zero or unity.]
+
+[h4 Applications]
+
+The arcsine distribution is useful to describe
+[@http://en.wikipedia.org/wiki/Random_walk Random walks], (including drunken walks)
+[@http://en.wikipedia.org/wiki/Brownian_motion Brownian motion],
+[@http://en.wikipedia.org/wiki/Wiener_process Weiner processes],
+[@http://en.wikipedia.org/wiki/Bernoulli_trial Bernoulli trials],
+and their appplication to solve stock market and other
+[@http://en.wikipedia.org/wiki/Gambler%27s_ruin ruinous gambling games].
+
+The random variate ['x] is constrained to ['x_min] and ['x_max], (for our 'standard' distribution, 0 and 1),
+and is usually some fraction. For any other ['x_min] and ['x_max] a fraction can be obtained from ['x] using
+
+[sixemspace] fraction = (x - x_min) / (x_max - x_min)
+
+The simplest example is tossing heads and tails with a fair coin and modelling the risk of losing, or winning.
+Walkers (molecules, drunks...) moving left or right of a centre line are another common example.
+
+The random variate ['x] is the fraction of time spent on the 'winning' side.
+If half the time is spent on the 'winning' side (and so the other half on the 'losing' side) then ['x = 1/2].
+
+For large numbers of tosses, this is modelled by the (standard \[0,1\]) arcsine distribution,
+and the PDF can be calculated thus:
+
+[arcsine_snip_2]
+
+From the plot of PDF, it is clear that ['x] = [frac12] is the [*minimum] of the curve,
+so this is the [*least likely] scenario.
+(This is highly counter-intuitive, considering that fair tosses must [*eventually] become equal.
+It turns out that ['eventually] is not just very long, but [*infinite]!).
+
+The [*most likely] scenarios are towards the extrema where ['x] = 0 or ['x] = 1.
+
+If fraction of time on the left is a [frac14],
+it is only slightly more likely because the curve is quite flat bottomed.
+
+[arcsine_snip_3]
+
+If we consider fair coin-tossing games being played for 100 days
+(hypothetically continuously to be 'at-limit')
+the person winning after day 5 will not change in fraction 0.144 of the cases.
+
+We can easily compute this setting ['x] = 5./100 = 0.05
+
+[arcsine_snip_4]
+
+Similarly, we can compute from a fraction of 0.05 /2 = 0.025
+(halved because we are considering both winners and losers)
+corresponding to 1 - 0.025 or 97.5% of the gamblers, (walkers, particles...) on the [*same side] of the origin
+
+[arcsine_snip_5]
+
+(use of the complement gives a bit more clarity,
+and avoids potential loss of accuracy when ['x] is close to unity, see __why_complements).
+
+[arcsine_snip_6]
+
+or we can reverse the calculation by assuming a fraction of time on one side, say fraction 0.2,
+
+[arcsine_snip_7]
+
+[*Summary]: Every time we toss, the odds are equal,
+so on average we have the same change of winning and losing.
+
+But this is [*not true] for an an individual game where one will be [*mostly in a bad or good patch].
+
+This is quite counter-intuitive to most people, but the mathematics is clear,
+and gamblers continue to provide proof.
+
+[*Moral]: if you in a losing patch, leave the game.
+(Because the odds to recover to a good patch are poor).
+
+[*Corollary]: Quit while you are ahead?
+
+A working example is at [@../../example/arcsine_example.cpp arcsine_example.cpp]
+including sample output .
+
+[h4 Related distributions]
+
+The arcsine distribution with ['x_min = 0] and ['x_max = 1] is special case of the
+__beta_distrib with [alpha] = 1/2 and [beta] = 1/2.
+
+[h4 Accuracy]
+
+This distribution is implemented using sqrt, sine, cos and arc sine and cos trigonometric functions
+which are normally accurate to a few __epsilon.
+But all values suffer from [@http://en.wikipedia.org/wiki/Loss_of_significance loss of significance or cancellation error]
+for values of ['x] close to ['x_max].
+For example, for a standard [0, 1] arcsine distribution ['as], the pdf is symmetric about random variate ['x = 0.5]
+so that one would expect `pdf(as, 0.01) == pdf(as, 0.99)`. But as ['x] nears unity, there is increasing
+[@http://en.wikipedia.org/wiki/Loss_of_significance loss of significance].
+To counteract this, the complement versions of CDF and quantile
+are implemented with alternative expressions using ['cos[super -1]] instead of ['sin[super -1]].
+Users should see __why_complements for guidance on when to avoid loss of accuracy by using complements.
+
+[h4 Testing]
+The results were tested against a few accurate spot values computed by __WolframAlpha, for example:
+
+ N[PDF[arcsinedistribution[0, 1], 0.5], 50]
+ 0.63661977236758134307553505349005744813783858296183
+
+[h4 Implementation]
+
+In the following table ['a] and ['b] are the parameters ['x_min][space] and ['x_max],
+['x] is the random variable, ['p] is the probability and its complement ['q = 1-p].
+
+[table
+[[Function][Implementation Notes]]
+[[support] [x [isin] \[a, b\], default x [isin] \[0, 1\] ]]
+[[pdf] [f(x; a, b) = 1/([pi][sdot][sqrt](x - a)[sdot](b - x))]]
+[[cdf] [F(x) = 2/[pi][sdot]sin[super-1]([sqrt](x - a) / (b - a) ) ]]
+[[cdf of complement] [2/([pi][sdot]cos[super-1]([sqrt](x - a) / (b - a)))]]
+[[quantile] [-a[sdot]sin[super 2]([frac12][pi][sdot]p) + a + b[sdot]sin[super 2]([frac12][pi][sdot]p)]]
+[[quantile from the complement] [-a[sdot]cos[super 2]([frac12][pi][sdot]p) + a + b[sdot]cos[super 2]([frac12][pi][sdot]q)]]
+[[mean] [[frac12](a+b)]]
+[[median] [[frac12](a+b)]]
+[[mode] [ x [isin] \[a, b\], so raises domain_error (returning NaN).]]
+[[variance] [(b - a)[super 2] / 8]]
+[[skewness] [0]]
+[[kurtosis excess] [ -3/2 ]]
+[[kurtosis] [kurtosis_excess + 3]]
+]
+
+The quantile was calculated using an expression obtained by using __WolframAlpha
+to invert the formula for the CDF thus
+
+ solve [p - 2/pi sin^-1(sqrt((x-a)/(b-a))) = 0, x]
+
+which was interpreted as
+
+ Solve[p - (2 ArcSin[Sqrt[(-a + x)/(-a + b)]])/Pi == 0, x, MaxExtraConditions -> Automatic]
+
+and produced the resulting expression
+
+ x = -a sin^2((pi p)/2)+a+b sin^2((pi p)/2)
+
+Thanks to Wolfram for providing this facility.
+
+[h4 References]
+
+* [@http://en.wikipedia.org/wiki/arcsine_distribution Wikipedia arcsine distribution]
+* [@http://en.wikipedia.org/wiki/Beta_distribution Wikipedia Beta distribution]
+* [@http://mathworld.wolfram.com/BetaDistribution.html Wolfram MathWorld]
+* [@http://www.wolframalpha.com/ Wolfram Alpha]
+
+[h4 Sources]
+
+*[@http://estebanmoro.org/2009/04/the-probability-of-going-through-a-bad-patch The probability of going through a bad patch] Esteban Moro's Blog.
+*[@http://www.gotohaggstrom.com/What%20do%20schmucks%20and%20the%20arc%20sine%20law%20have%20in%20common.pdf What soschumcks and the arc sine have in common] Peter Haggstrom.
+*[@http://www.math.uah.edu/stat/special/Arcsine.html arcsine distribution].
+*[@http://reference.wolfram.com/language/ref/ArcSinDistribution.html Wolfram reference arcsine examples].
+*[@http://www.math.harvard.edu/library/sternberg/slides/1180908.pdf Shlomo Sternberg slides].
+
+
+[endsect] [/section:arcsine_dist arcsine]
+
+[/ arcsine.qbk
+ Copyright 2014 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).
+]
diff --git a/doc/distributions/background.qbk b/doc/distributions/background.qbk
new file mode 100644
index 0000000..09cb043
--- /dev/null
+++ b/doc/distributions/background.qbk
@@ -0,0 +1,84 @@
+[section:variates 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 after the __random_variate (whose value you 'choose'),
+to separate the variate from the parameter(s) that defines the shape of the distribution.
+
+For example, the binomial distribution has two parameters:
+n (the number of trials) and p (the probability of success on one trial).
+It also has the __random_variate /k/: the number of successes observed.
+This means the probability density\/mass function (pdf) is written as ['f(k; n, p)].
+
+Translating this into code the `binomial_distribution` constructor
+therefore has two parameters:
+
+ binomial_distribution(RealType n, RealType p);
+
+While the function `pdf` has one argument specifying the distribution type
+(which includes its parameters, if any),
+and a second argument for the __random_variate. So taking our binomial distribution
+example, we would write:
+
+ pdf(binomial_distribution<RealType>(n, p), k);
+
+[endsect]
+
+[section:dist_params 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:
+only integral values of the __random_variate are envisaged
+and the functions are only defined at these integral values.
+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.
+
+To enforce a strict mathematical model,
+users may use floor or ceil functions on the __random_variate,
+prior to calling the distribution function, to enforce integral values.
+
+For similar reasons, in continuous distributions, 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, that there are a small number of situations where non-integral
+degrees of freedom do have a genuine meaning.
+
+Generally speaking there is no loss of performance from allowing real-values
+parameters: the underlying special functions contain optimizations for
+integer-valued arguments when applicable.
+
+[caution
+The quantile function of a discrete distribution will by
+default return an integer result that has been
+/rounded outwards/. That is to say lower quantiles (where the probability is
+less than 0.5) are rounded downward, and upper quantiles (where the probability
+is greater than 0.5) are rounded upwards. 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 even return a real-valued result using
+[link math_toolkit.pol_overview Policies]. It is strongly
+recommended that you read the tutorial
+[link math_toolkit.pol_tutorial.understand_dis_quant
+Understanding Quantiles of Discrete Distributions] before
+using the quantile function on a discrete distribution. The
+[link math_toolkit.pol_ref.discrete_quant_ref reference docs]
+describe how to change the rounding policy
+for these distributions.
+]
+
+[endsect]
+
+[/
+ 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).
+]
+
+
diff --git a/doc/distributions/bernoulli.qbk b/doc/distributions/bernoulli.qbk
new file mode 100644
index 0000000..ae9c577
--- /dev/null
+++ b/doc/distributions/bernoulli.qbk
@@ -0,0 +1,118 @@
+[section:bernoulli_dist Bernoulli Distribution]
+
+``#include <boost/math/distributions/bernoulli.hpp>``
+
+ namespace boost{ namespace math{
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class bernoulli_distribution;
+
+ typedef bernoulli_distribution<> bernoulli;
+
+ template <class RealType, class ``__Policy``>
+ class bernoulli_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ bernoulli_distribution(RealType p); // Constructor.
+ // Accessor function.
+ RealType success_fraction() const
+ // Probability of success (as a fraction).
+ };
+ }} // namespaces
+
+The Bernoulli distribution is a discrete distribution of the outcome
+of a single trial with only two results, 0 (failure) or 1 (success),
+with a probability of success p.
+
+The Bernoulli distribution is the simplest building block
+on which other discrete distributions of
+sequences of independent Bernoulli trials can be based.
+
+The Bernoulli is the binomial distribution (k = 1, p) with only one trial.
+
+[@http://en.wikipedia.org/wiki/Probability_density_function probability density function pdf]
+f(0) = 1 - p, f(1) = p.
+[@http://en.wikipedia.org/wiki/Cumulative_Distribution_Function Cumulative distribution function]
+D(k) = if (k == 0) 1 - p else 1.
+
+The following graph illustrates how the
+[@http://en.wikipedia.org/wiki/Probability_density_function probability density function pdf]
+varies with the outcome of the single trial:
+
+[graph bernoulli_pdf]
+
+and the [@http://en.wikipedia.org/wiki/Cumulative_Distribution_Function Cumulative distribution function]
+
+[graph bernoulli_cdf]
+
+[h4 Member Functions]
+
+ bernoulli_distribution(RealType p);
+
+Constructs a [@http://en.wikipedia.org/wiki/bernoulli_distribution
+bernoulli distribution] with success_fraction /p/.
+
+ RealType success_fraction() const
+
+Returns the /success_fraction/ parameter of this distribution.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
+that are generic to all distributions are supported: __usual_accessors.
+
+The domain of the random variable is 0 and 1,
+and the useful supported range is only 0 or 1.
+
+Outside this range, functions are undefined, or may throw domain_error exception
+and make an error message available.
+
+[h4 Accuracy]
+
+The Bernoulli distribution is implemented with simple arithmetic operators
+and so should have errors within an epsilon or two.
+
+[h4 Implementation]
+
+In the following table /p/ is the probability of success and /q = 1-p/.
+/k/ is the random variate, either 0 or 1.
+
+[note The Bernoulli distribution is implemented here as a /strict discrete/ distribution.
+If a generalised version, allowing k to be any real, is required then
+the binomial distribution with a single trial should be used, for example:
+
+`binomial_distribution(1, 0.25)`
+]
+
+[table
+[[Function][Implementation Notes]]
+[[Supported range][{0, 1}]]
+[[pdf][Using the relation: pdf = 1 - p for k = 0, else p ]]
+[[cdf][Using the relation: cdf = 1 - p for k = 0, else 1]]
+[[cdf complement][q = 1 - p]]
+[[quantile][if x <= (1-p) 0 else 1]]
+[[quantile from the complement][if x <= (1-p) 1 else 0]]
+[[mean][p]]
+[[variance][p * (1 - p)]]
+[[mode][if (p < 0.5) 0 else 1]]
+[[skewness][(1 - 2 * p) / sqrt(p * q)]]
+[[kurtosis][6 * p * p - 6 * p +1/ p * q]]
+[[kurtosis excess][kurtosis -3]]
+]
+
+[h4 References]
+* [@http://en.wikipedia.org/wiki/Bernoulli_distribution Wikpedia Bernoulli distribution]
+* [@http://mathworld.wolfram.com/BernoulliDistribution.html Weisstein, Eric W. "Bernoulli Distribution." From MathWorld--A Wolfram Web Resource.]
+
+[endsect] [/section:bernoulli_dist bernoulli]
+
+[/
+ 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).
+]
+
diff --git a/doc/distributions/beta.qbk b/doc/distributions/beta.qbk
new file mode 100644
index 0000000..97ca017
--- /dev/null
+++ b/doc/distributions/beta.qbk
@@ -0,0 +1,280 @@
+[section:beta_dist Beta Distribution]
+
+``#include <boost/math/distributions/beta.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class beta_distribution;
+
+ // typedef beta_distribution<double> beta;
+ // Note that this is deliberately NOT provided,
+ // to avoid a clash with the function name beta.
+
+ template <class RealType, class ``__Policy``>
+ class beta_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+ // Constructor from two shape parameters, alpha & beta:
+ beta_distribution(RealType a, RealType b);
+
+ // Parameter accessors:
+ RealType alpha() const;
+ RealType beta() const;
+
+ // Parameter estimators of alpha or beta from mean and variance.
+ static RealType find_alpha(
+ RealType mean, // Expected value of mean.
+ RealType variance); // Expected value of variance.
+
+ static RealType find_beta(
+ RealType mean, // Expected value of mean.
+ RealType variance); // Expected value of variance.
+
+ // Parameter estimators from
+ // either alpha or beta, and x and probability.
+
+ static RealType find_alpha(
+ RealType beta, // from beta.
+ RealType x, // x.
+ RealType probability); // cdf
+
+ static RealType find_beta(
+ RealType alpha, // alpha.
+ RealType x, // probability x.
+ RealType probability); // probability cdf.
+ };
+
+ }} // namespaces
+
+The class type `beta_distribution` represents a
+[@http://en.wikipedia.org/wiki/Beta_distribution beta ]
+[@http://en.wikipedia.org/wiki/Probability_distribution probability distribution function].
+
+The [@http://mathworld.wolfram.com/BetaDistribution.htm beta distribution ]
+is used as a [@http://en.wikipedia.org/wiki/Prior_distribution prior distribution]
+for binomial proportions in
+[@http://mathworld.wolfram.com/BayesianAnalysis.html Bayesian analysis].
+
+See also:
+[@http://documents.wolfram.com/calculationcenter/v2/Functions/ListsMatrices/Statistics/BetaDistribution.html beta distribution]
+and [@http://en.wikipedia.org/wiki/Bayesian_statistics Bayesian statistics].
+
+How the beta distribution is used for
+[@http://home.uchicago.edu/~grynav/bayes/ABSLec5.ppt
+Bayesian analysis of one parameter models]
+is discussed by Jeff Grynaviski.
+
+The [@http://en.wikipedia.org/wiki/Probability_density_function probability density function PDF]
+for the [@http://en.wikipedia.org/wiki/Beta_distribution beta distribution]
+defined on the interval \[0,1\] is given by:
+
+f(x;[alpha],[beta]) = x[super[alpha] - 1] (1 - x)[super[beta] -1] / B([alpha], [beta])
+
+where B([alpha], [beta]) is the
+[@http://en.wikipedia.org/wiki/Beta_function beta function],
+implemented in this library as __beta. Division by the beta function
+ensures that the pdf is normalized to the range zero to unity.
+
+The following graph illustrates examples of the pdf for various values
+of the shape parameters. Note the [alpha] = [beta] = 2 (blue line)
+is dome-shaped, and might be approximated by a symmetrical triangular
+distribution.
+
+[graph beta_pdf]
+
+If [alpha] = [beta] = 1, then it is a __space
+[@http://en.wikipedia.org/wiki/Uniform_distribution_%28continuous%29 uniform distribution],
+equal to unity in the entire interval x = 0 to 1.
+If [alpha] __space and [beta] __space are < 1, then the pdf is U-shaped.
+If [alpha] != [beta], then the shape is asymmetric
+and could be approximated by a triangle
+whose apex is away from the centre (where x = half).
+
+[h4 Member Functions]
+
+[h5 Constructor]
+
+ beta_distribution(RealType alpha, RealType beta);
+
+Constructs a beta distribution with shape parameters /alpha/ and /beta/.
+
+Requires alpha,beta > 0,otherwise __domain_error is called. Note that
+technically the beta distribution is defined for alpha,beta >= 0, but
+it's not clear whether any program can actually make use of that latitude
+or how many of the non-member functions can be usefully defined in that case.
+Therefore for now, we regard it as an error if alpha or beta is zero.
+
+For example:
+
+ beta_distribution<> mybeta(2, 5);
+
+Constructs a the beta distribution with alpha=2 and beta=5 (shown in yellow
+in the graph above).
+
+[h5 Parameter Accessors]
+
+ RealType alpha() const;
+
+Returns the parameter /alpha/ from which this distribution was constructed.
+
+ RealType beta() const;
+
+Returns the parameter /beta/ from which this distribution was constructed.
+
+So for example:
+
+ beta_distribution<> mybeta(2, 5);
+ assert(mybeta.alpha() == 2.); // mybeta.alpha() returns 2
+ assert(mybeta.beta() == 5.); // mybeta.beta() returns 5
+
+[h4 Parameter Estimators]
+
+Two pairs of parameter estimators are provided.
+
+One estimates either [alpha] __space or [beta] __space
+from presumed-known mean and variance.
+
+The other pair estimates either [alpha] __space or [beta] __space from
+the cdf and x.
+
+It is also possible to estimate [alpha] __space and [beta] __space from
+'known' mode & quantile. For example, calculators are provided by the
+[@http://www.ausvet.com.au/pprev/content.php?page=PPscript
+Pooled Prevalence Calculator] and
+[@http://www.epi.ucdavis.edu/diagnostictests/betabuster.html Beta Buster]
+but this is not yet implemented here.
+
+ static RealType find_alpha(
+ RealType mean, // Expected value of mean.
+ RealType variance); // Expected value of variance.
+
+Returns the unique value of [alpha][space] that corresponds to a
+beta distribution with mean /mean/ and variance /variance/.
+
+ static RealType find_beta(
+ RealType mean, // Expected value of mean.
+ RealType variance); // Expected value of variance.
+
+Returns the unique value of [beta][space] that corresponds to a
+beta distribution with mean /mean/ and variance /variance/.
+
+ static RealType find_alpha(
+ RealType beta, // from beta.
+ RealType x, // x.
+ RealType probability); // probability cdf
+
+Returns the value of [alpha][space] that gives:
+`cdf(beta_distribution<RealType>(alpha, beta), x) == probability`.
+
+ static RealType find_beta(
+ RealType alpha, // alpha.
+ RealType x, // probability x.
+ RealType probability); // probability cdf.
+
+Returns the value of [beta][space] that gives:
+`cdf(beta_distribution<RealType>(alpha, beta), x) == probability`.
+
+[h4 Non-member Accessor Functions]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
+that are generic to all distributions are supported: __usual_accessors.
+
+The formulae for calculating these are shown in the table below, and at
+[@http://mathworld.wolfram.com/BetaDistribution.html Wolfram Mathworld].
+
+[h4 Applications]
+
+The beta distribution can be used to model events constrained
+to take place within an interval defined by a minimum and maximum value:
+so it is used in project management systems.
+
+It is also widely used in [@http://en.wikipedia.org/wiki/Bayesian_inference Bayesian statistical inference].
+
+[h4 Related distributions]
+
+The beta distribution with both [alpha] __space and [beta] = 1 follows a
+[@http://en.wikipedia.org/wiki/Uniform_distribution_%28continuous%29 uniform distribution].
+
+The [@http://en.wikipedia.org/wiki/Triangular_distribution triangular]
+is used when less precise information is available.
+
+The [@http://en.wikipedia.org/wiki/Binomial_distribution binomial distribution]
+is closely related when [alpha] __space and [beta] __space are integers.
+
+With integer values of [alpha] __space and [beta] __space the distribution B(i, j) is
+that of the j-th highest of a sample of i + j + 1 independent random variables
+uniformly distributed between 0 and 1.
+The cumulative probability from 0 to x is thus
+the probability that the j-th highest value is less than x.
+Or it is the probability that at least i of the random variables are less than x,
+a probability given by summing over the __binomial_distrib
+with its p parameter set to x.
+
+[h4 Accuracy]
+
+This distribution is implemented using the
+[link math_toolkit.sf_beta.beta_function beta functions] __beta and
+[link math_toolkit.sf_beta.ibeta_function incomplete beta functions] __ibeta and __ibetac;
+please refer to these functions for information on accuracy.
+
+[h4 Implementation]
+
+In the following table /a/ and /b/ are the parameters [alpha][space] and [beta],
+/x/ is the random variable, /p/ is the probability and /q = 1-p/.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf]
+ [f(x;[alpha],[beta]) = x[super[alpha] - 1] (1 - x)[super[beta] -1] / B([alpha], [beta])
+
+ Implemented using __ibeta_derivative(a, b, x).]]
+
+[[cdf][Using the incomplete beta function __ibeta(a, b, x)]]
+[[cdf complement][__ibetac(a, b, x)]]
+[[quantile][Using the inverse incomplete beta function __ibeta_inv(a, b, p)]]
+[[quantile from the complement][__ibetac_inv(a, b, q)]]
+[[mean][`a/(a+b)`]]
+[[variance][`a * b / (a+b)^2 * (a + b + 1)`]]
+[[mode][`(a-1) / (a + b - 2)`]]
+[[skewness][`2 (b-a) sqrt(a+b+1)/(a+b+2) * sqrt(a * b)`]]
+[[kurtosis excess][ [equation beta_dist_kurtosis] ]]
+[[kurtosis][`kurtosis + 3`]]
+[[parameter estimation][ ]]
+[[alpha
+
+ from mean and variance][`mean * (( (mean * (1 - mean)) / variance)- 1)`]]
+[[beta
+
+ from mean and variance][`(1 - mean) * (((mean * (1 - mean)) /variance)-1)`]]
+[[The member functions `find_alpha` and `find_beta`
+
+ from cdf and probability x
+
+ and *either* `alpha` or `beta`]
+ [Implemented in terms of the inverse incomplete beta functions
+
+__ibeta_inva, and __ibeta_invb respectively.]]
+[[`find_alpha`][`ibeta_inva(beta, x, probability)`]]
+[[`find_beta`][`ibeta_invb(alpha, x, probability)`]]
+]
+
+[h4 References]
+
+[@http://en.wikipedia.org/wiki/Beta_distribution Wikipedia Beta distribution]
+
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda366h.htm NIST Exploratory Data Analysis]
+
+[@http://mathworld.wolfram.com/BetaDistribution.html Wolfram MathWorld]
+
+[endsect][/section:beta_dist beta]
+
+[/ beta.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).
+]
diff --git a/doc/distributions/binomial.qbk b/doc/distributions/binomial.qbk
new file mode 100644
index 0000000..eae3e83
--- /dev/null
+++ b/doc/distributions/binomial.qbk
@@ -0,0 +1,404 @@
+[section:binomial_dist Binomial Distribution]
+
+``#include <boost/math/distributions/binomial.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class binomial_distribution;
+
+ typedef binomial_distribution<> binomial;
+
+ template <class RealType, class ``__Policy``>
+ class binomial_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ static const ``['unspecified-type]`` clopper_pearson_exact_interval;
+ static const ``['unspecified-type]`` jeffreys_prior_interval;
+
+ // construct:
+ binomial_distribution(RealType n, RealType p);
+
+ // parameter access::
+ RealType success_fraction() const;
+ RealType trials() const;
+
+ // Bounds on success fraction:
+ static RealType find_lower_bound_on_p(
+ RealType trials,
+ RealType successes,
+ RealType probability,
+ ``['unspecified-type]`` method = clopper_pearson_exact_interval);
+ static RealType find_upper_bound_on_p(
+ RealType trials,
+ RealType successes,
+ RealType probability,
+ ``['unspecified-type]`` method = clopper_pearson_exact_interval);
+
+ // estimate min/max number of trials:
+ static RealType find_minimum_number_of_trials(
+ RealType k, // number of events
+ RealType p, // success fraction
+ RealType alpha); // risk level
+
+ static RealType find_maximum_number_of_trials(
+ RealType k, // number of events
+ RealType p, // success fraction
+ RealType alpha); // risk level
+ };
+
+ }} // namespaces
+
+The class type `binomial_distribution` represents a
+[@http://mathworld.wolfram.com/BinomialDistribution.html binomial distribution]:
+it is used when there are exactly two mutually
+exclusive outcomes of a trial. These outcomes are labelled
+"success" and "failure". The
+__binomial_distrib is used to obtain
+the probability of observing k successes in N trials, with the
+probability of success on a single trial denoted by p. The
+binomial distribution assumes that p is fixed for all trials.
+
+[note The random variable for the binomial distribution is the number of successes,
+(the number of trials is a fixed property of the distribution)
+whereas for the negative binomial,
+the random variable is the number of trials, for a fixed number of successes.]
+
+The PDF for the binomial distribution is given by:
+
+[equation binomial_ref2]
+
+The following two graphs illustrate how the PDF changes depending
+upon the distributions parameters, first we'll keep the success
+fraction /p/ fixed at 0.5, and vary the sample size:
+
+[graph binomial_pdf_1]
+
+Alternatively, we can keep the sample size fixed at N=20 and
+vary the success fraction /p/:
+
+[graph binomial_pdf_2]
+
+[discrete_quantile_warning Binomial]
+
+[h4 Member Functions]
+
+[h5 Construct]
+
+ binomial_distribution(RealType n, RealType p);
+
+Constructor: /n/ is the total number of trials, /p/ is the
+probability of success of a single trial.
+
+Requires `0 <= p <= 1`, and `n >= 0`, otherwise calls __domain_error.
+
+[h5 Accessors]
+
+ RealType success_fraction() const;
+
+Returns the parameter /p/ from which this distribution was constructed.
+
+ RealType trials() const;
+
+Returns the parameter /n/ from which this distribution was constructed.
+
+[h5 Lower Bound on the Success Fraction]
+
+ static RealType find_lower_bound_on_p(
+ RealType trials,
+ RealType successes,
+ RealType alpha,
+ ``['unspecified-type]`` method = clopper_pearson_exact_interval);
+
+Returns a lower bound on the success fraction:
+
+[variablelist
+[[trials][The total number of trials conducted.]]
+[[successes][The number of successes that occurred.]]
+[[alpha][The largest acceptable probability that the true value of
+ the success fraction is [*less than] the value returned.]]
+[[method][An optional parameter that specifies the method to be used
+ to compute the interval (See below).]]
+]
+
+For example, if you observe /k/ successes from /n/ trials the
+best estimate for the success fraction is simply ['k/n], but if you
+want to be 95% sure that the true value is [*greater than] some value,
+['p[sub min]], then:
+
+ p``[sub min]`` = binomial_distribution<RealType>::find_lower_bound_on_p(
+ n, k, 0.05);
+
+[link math_toolkit.stat_tut.weg.binom_eg.binom_conf See worked example.]
+
+There are currently two possible values available for the /method/
+optional parameter: /clopper_pearson_exact_interval/
+or /jeffreys_prior_interval/. These constants are both members of
+class template `binomial_distribution`, so usage is for example:
+
+ p = binomial_distribution<RealType>::find_lower_bound_on_p(
+ n, k, 0.05, binomial_distribution<RealType>::jeffreys_prior_interval);
+
+The default method if this parameter is not specified is the Clopper Pearson
+"exact" interval. This produces an interval that guarantees at least
+`100(1-alpha)%` coverage, but which is known to be overly conservative,
+sometimes producing intervals with much greater than the requested coverage.
+
+The alternative calculation method produces a non-informative
+Jeffreys Prior interval. It produces `100(1-alpha)%` coverage only
+['in the average case], though is typically very close to the requested
+coverage level. It is one of the main methods of calculation recommended
+in the review by Brown, Cai and DasGupta.
+
+Please note that the "textbook" calculation method using
+a normal approximation (the Wald interval) is deliberately
+not provided: it is known to produce consistently poor results,
+even when the sample size is surprisingly large.
+Refer to Brown, Cai and DasGupta for a full explanation. Many other methods
+of calculation are available, and may be more appropriate for specific
+situations. Unfortunately there appears to be no consensus amongst
+statisticians as to which is "best": refer to the discussion at the end of
+Brown, Cai and DasGupta for examples.
+
+The two methods provided here were chosen principally because they
+can be used for both one and two sided intervals.
+See also:
+
+Lawrence D. Brown, T. Tony Cai and Anirban DasGupta (2001),
+Interval Estimation for a Binomial Proportion,
+Statistical Science, Vol. 16, No. 2, 101-133.
+
+T. Tony Cai (2005),
+One-sided confidence intervals in discrete distributions,
+Journal of Statistical Planning and Inference 131, 63-88.
+
+Agresti, A. and Coull, B. A. (1998). Approximate is better than
+"exact" for interval estimation of binomial proportions. Amer.
+Statist. 52 119-126.
+
+Clopper, C. J. and Pearson, E. S. (1934). The use of confidence
+or fiducial limits illustrated in the case of the binomial.
+Biometrika 26 404-413.
+
+[h5 Upper Bound on the Success Fraction]
+
+ static RealType find_upper_bound_on_p(
+ RealType trials,
+ RealType successes,
+ RealType alpha,
+ ``['unspecified-type]`` method = clopper_pearson_exact_interval);
+
+Returns an upper bound on the success fraction:
+
+[variablelist
+[[trials][The total number of trials conducted.]]
+[[successes][The number of successes that occurred.]]
+[[alpha][The largest acceptable probability that the true value of
+ the success fraction is [*greater than] the value returned.]]
+[[method][An optional parameter that specifies the method to be used
+ to compute the interval. Refer to the documentation for
+ `find_upper_bound_on_p` above for the meaning of the
+ method options.]]
+]
+
+For example, if you observe /k/ successes from /n/ trials the
+best estimate for the success fraction is simply ['k/n], but if you
+want to be 95% sure that the true value is [*less than] some value,
+['p[sub max]], then:
+
+ p``[sub max]`` = binomial_distribution<RealType>::find_upper_bound_on_p(
+ n, k, 0.05);
+
+[link math_toolkit.stat_tut.weg.binom_eg.binom_conf See worked example.]
+
+[note
+In order to obtain a two sided bound on the success fraction, you
+call both `find_lower_bound_on_p` *and* `find_upper_bound_on_p`
+each with the same arguments.
+
+If the desired risk level
+that the true success fraction lies outside the bounds is [alpha],
+then you pass [alpha]/2 to these functions.
+
+So for example a two sided 95% confidence interval would be obtained
+by passing [alpha] = 0.025 to each of the functions.
+
+[link math_toolkit.stat_tut.weg.binom_eg.binom_conf See worked example.]
+]
+
+
+[h5 Estimating the Number of Trials Required for a Certain Number of Successes]
+
+ static RealType find_minimum_number_of_trials(
+ RealType k, // number of events
+ RealType p, // success fraction
+ RealType alpha); // probability threshold
+
+This function estimates the minimum number of trials required to ensure that
+more than k events is observed with a level of risk /alpha/ that k or
+fewer events occur.
+
+[variablelist
+[[k][The number of success observed.]]
+[[p][The probability of success for each trial.]]
+[[alpha][The maximum acceptable probability that k events or fewer will be observed.]]
+]
+
+For example:
+
+ binomial_distribution<RealType>::find_number_of_trials(10, 0.5, 0.05);
+
+Returns the smallest number of trials we must conduct to be 95% sure
+of seeing 10 events that occur with frequency one half.
+
+[h5 Estimating the Maximum Number of Trials to Ensure no more than a Certain Number of Successes]
+
+ static RealType find_maximum_number_of_trials(
+ RealType k, // number of events
+ RealType p, // success fraction
+ RealType alpha); // probability threshold
+
+This function estimates the maximum number of trials we can conduct
+to ensure that k successes or fewer are observed, with a risk /alpha/
+that more than k occur.
+
+[variablelist
+[[k][The number of success observed.]]
+[[p][The probability of success for each trial.]]
+[[alpha][The maximum acceptable probability that more than k events will be observed.]]
+]
+
+For example:
+
+ binomial_distribution<RealType>::find_maximum_number_of_trials(0, 1e-6, 0.05);
+
+Returns the largest number of trials we can conduct and still be 95% certain
+of not observing any events that occur with one in a million frequency.
+This is typically used in failure analysis.
+
+[link math_toolkit.stat_tut.weg.binom_eg.binom_size_eg See Worked Example.]
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
+that are generic to all distributions are supported: __usual_accessors.
+
+The domain for the random variable /k/ is `0 <= k <= N`, otherwise a
+__domain_error is returned.
+
+It's worth taking a moment to define what these accessors actually mean in
+the context of this distribution:
+
+[table Meaning of the non-member accessors
+[[Function][Meaning]]
+[[__pdf]
+ [The probability of obtaining [*exactly k successes] from n trials
+ with success fraction p. For example:
+
+`pdf(binomial(n, p), k)`]]
+[[__cdf]
+ [The probability of obtaining [*k successes or fewer] from n trials
+ with success fraction p. For example:
+
+`cdf(binomial(n, p), k)`]]
+[[__ccdf]
+ [The probability of obtaining [*more than k successes] from n trials
+ with success fraction p. For example:
+
+`cdf(complement(binomial(n, p), k))`]]
+[[__quantile]
+ [The [*greatest] number of successes that may be observed from n trials
+ with success fraction p, at probability P. Note that the value returned
+ is a real-number, and not an integer. Depending on the use case you may
+ want to take either the floor or ceiling of the result. For example:
+
+`quantile(binomial(n, p), P)`]]
+[[__quantile_c]
+ [The [*smallest] number of successes that may be observed from n trials
+ with success fraction p, at probability P. Note that the value returned
+ is a real-number, and not an integer. Depending on the use case you may
+ want to take either the floor or ceiling of the result. For example:
+
+`quantile(complement(binomial(n, p), P))`]]
+]
+
+[h4 Examples]
+
+Various [link math_toolkit.stat_tut.weg.binom_eg worked examples]
+are available illustrating the use of the binomial distribution.
+
+[h4 Accuracy]
+
+This distribution is implemented using the
+incomplete beta functions __ibeta and __ibetac,
+please refer to these functions for information on accuracy.
+
+[h4 Implementation]
+
+In the following table /p/ is the probability that one trial will
+be successful (the success fraction), /n/ is the number of trials,
+/k/ is the number of successes, /p/ is the probability and /q = 1-p/.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Implementation is in terms of __ibeta_derivative: if [sub n]C[sub k ] is the binomial
+ coefficient of a and b, then we have:
+
+[equation binomial_ref1]
+
+Which can be evaluated as `ibeta_derivative(k+1, n-k+1, p) / (n+1)`
+
+The function __ibeta_derivative is used here, since it has already
+ been optimised for the lowest possible error - indeed this is really
+ just a thin wrapper around part of the internals of the incomplete
+ beta function.
+
+There are also various special cases: refer to the code for details.
+ ]]
+[[cdf][Using the relation:
+
+``
+p = I[sub 1-p](n - k, k + 1)
+ = 1 - I[sub p](k + 1, n - k)
+ = __ibetac(k + 1, n - k, p)``
+
+There are also various special cases: refer to the code for details.
+]]
+[[cdf complement][Using the relation: q = __ibeta(k + 1, n - k, p)
+
+There are also various special cases: refer to the code for details. ]]
+[[quantile][Since the cdf is non-linear in variate /k/ none of the inverse
+ incomplete beta functions can be used here. Instead the quantile
+ is found numerically using a derivative free method
+ (__root_finding_TOMS748).]]
+[[quantile from the complement][Found numerically as above.]]
+[[mean][ `p * n` ]]
+[[variance][ `p * n * (1-p)` ]]
+[[mode][`floor(p * (n + 1))`]]
+[[skewness][`(1 - 2 * p) / sqrt(n * p * (1 - p))`]]
+[[kurtosis][`3 - (6 / n) + (1 / (n * p * (1 - p)))`]]
+[[kurtosis excess][`(1 - 6 * p * q) / (n * p * q)`]]
+[[parameter estimation][The member functions `find_upper_bound_on_p`
+ `find_lower_bound_on_p` and `find_number_of_trials` are
+ implemented in terms of the inverse incomplete beta functions
+ __ibetac_inv, __ibeta_inv, and __ibetac_invb respectively]]
+]
+
+[h4 References]
+
+* [@http://mathworld.wolfram.com/BinomialDistribution.html Weisstein, Eric W. "Binomial Distribution." From MathWorld--A Wolfram Web Resource].
+* [@http://en.wikipedia.org/wiki/Beta_distribution Wikipedia binomial distribution].
+* [@http://www.itl.nist.gov/div898/handbook/eda/section3/eda366i.htm NIST Explorary Data Analysis].
+
+[endsect] [/section:binomial_dist Binomial]
+
+[/ binomial.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).
+]
diff --git a/doc/distributions/binomial_example.qbk b/doc/distributions/binomial_example.qbk
new file mode 100644
index 0000000..7f03e51
--- /dev/null
+++ b/doc/distributions/binomial_example.qbk
@@ -0,0 +1,332 @@
+[section:binom_eg Binomial Distribution Examples]
+
+See also the reference documentation for the __binomial_distrib.
+
+[section:binomial_coinflip_example Binomial Coin-Flipping Example]
+
+[import ../../example/binomial_coinflip_example.cpp]
+[binomial_coinflip_example1]
+
+See [@../../example/binomial_coinflip_example.cpp binomial_coinflip_example.cpp]
+for full source code, the program output looks like this:
+
+[binomial_coinflip_example_output]
+
+[endsect] [/section:binomial_coinflip_example Binomial coinflip example]
+
+[section:binomial_quiz_example Binomial Quiz Example]
+
+[import ../../example/binomial_quiz_example.cpp]
+[binomial_quiz_example1]
+[binomial_quiz_example2]
+[discrete_quantile_real]
+
+See [@../../example/binomial_quiz_example.cpp binomial_quiz_example.cpp]
+for full source code and output.
+
+[endsect] [/section:binomial_coinflip_quiz Binomial Coin-Flipping example]
+
+[section:binom_conf Calculating Confidence Limits on the Frequency of Occurrence for a Binomial Distribution]
+
+Imagine you have a process that follows a binomial distribution: for each
+trial conducted, an event either occurs or does it does not, referred
+to as "successes" and "failures". If, by experiment, you want to measure the
+frequency with which successes occur, the best estimate is given simply
+by /k/ \/ /N/, for /k/ successes out of /N/ trials. However our confidence in that
+estimate will be shaped by how many trials were conducted, and how many successes
+were observed. The static member functions
+`binomial_distribution<>::find_lower_bound_on_p` and
+`binomial_distribution<>::find_upper_bound_on_p` allow you to calculate
+the confidence intervals for your estimate of the occurrence frequency.
+
+The sample program [@../../example/binomial_confidence_limits.cpp
+binomial_confidence_limits.cpp] illustrates their use. It begins by defining
+a procedure that will print a table of confidence limits for various degrees
+of certainty:
+
+ #include <iostream>
+ #include <iomanip>
+ #include <boost/math/distributions/binomial.hpp>
+
+ void confidence_limits_on_frequency(unsigned trials, unsigned successes)
+ {
+ //
+ // trials = Total number of trials.
+ // successes = Total number of observed successes.
+ //
+ // Calculate confidence limits for an observed
+ // frequency of occurrence that follows a binomial
+ // distribution.
+ //
+ using namespace std;
+ using namespace boost::math;
+
+ // Print out general info:
+ cout <<
+ "___________________________________________\n"
+ "2-Sided Confidence Limits For Success Ratio\n"
+ "___________________________________________\n\n";
+ cout << setprecision(7);
+ cout << setw(40) << left << "Number of Observations" << "= " << trials << "\n";
+ cout << setw(40) << left << "Number of successes" << "= " << successes << "\n";
+ cout << setw(40) << left << "Sample frequency of occurrence" << "= " << double(successes) / trials << "\n";
+
+The procedure now defines a table of significance levels: these are the
+probabilities that the true occurrence frequency lies outside the calculated
+interval:
+
+ double alpha[] = { 0.5, 0.25, 0.1, 0.05, 0.01, 0.001, 0.0001, 0.00001 };
+
+Some pretty printing of the table header follows:
+
+ cout << "\n\n"
+ "_______________________________________________________________________\n"
+ "Confidence Lower CP Upper CP Lower JP Upper JP\n"
+ " Value (%) Limit Limit Limit Limit\n"
+ "_______________________________________________________________________\n";
+
+
+And now for the important part - the intervals themselves - for each
+value of /alpha/, we call `find_lower_bound_on_p` and
+`find_lower_upper_on_p` to obtain lower and upper bounds
+respectively. Note that since we are calculating a two-sided interval,
+we must divide the value of alpha in two.
+
+Please note that calculating two separate /single sided bounds/, each with risk
+level [alpha][space]is not the same thing as calculating a two sided interval.
+Had we calculate two single-sided intervals each with a risk
+that the true value is outside the interval of [alpha], then:
+
+* The risk that it is less than the lower bound is [alpha].
+
+and
+
+* The risk that it is greater than the upper bound is also [alpha].
+
+So the risk it is outside *upper or lower bound*, is *twice* alpha, and the
+probability that it is inside the bounds is therefore not nearly as high as
+one might have thought. This is why [alpha]/2 must be used in
+the calculations below.
+
+In contrast, had we been calculating a
+single-sided interval, for example: ['"Calculate a lower bound so that we are P%
+sure that the true occurrence frequency is greater than some value"]
+then we would *not* have divided by two.
+
+Finally note that `binomial_distribution` provides a choice of two
+methods for the calculation, we print out the results from both
+methods in this example:
+
+ for(unsigned i = 0; i < sizeof(alpha)/sizeof(alpha[0]); ++i)
+ {
+ // Confidence value:
+ cout << fixed << setprecision(3) << setw(10) << right << 100 * (1-alpha[i]);
+ // Calculate Clopper Pearson bounds:
+ double l = binomial_distribution<>::find_lower_bound_on_p(
+ trials, successes, alpha[i]/2);
+ double u = binomial_distribution<>::find_upper_bound_on_p(
+ trials, successes, alpha[i]/2);
+ // Print Clopper Pearson Limits:
+ cout << fixed << setprecision(5) << setw(15) << right << l;
+ cout << fixed << setprecision(5) << setw(15) << right << u;
+ // Calculate Jeffreys Prior Bounds:
+ l = binomial_distribution<>::find_lower_bound_on_p(
+ trials, successes, alpha[i]/2,
+ binomial_distribution<>::jeffreys_prior_interval);
+ u = binomial_distribution<>::find_upper_bound_on_p(
+ trials, successes, alpha[i]/2,
+ binomial_distribution<>::jeffreys_prior_interval);
+ // Print Jeffreys Prior Limits:
+ cout << fixed << setprecision(5) << setw(15) << right << l;
+ cout << fixed << setprecision(5) << setw(15) << right << u << std::endl;
+ }
+ cout << endl;
+ }
+
+And that's all there is to it. Let's see some sample output for a 2 in 10
+success ratio, first for 20 trials:
+
+[pre'''___________________________________________
+2-Sided Confidence Limits For Success Ratio
+___________________________________________
+
+Number of Observations = 20
+Number of successes = 4
+Sample frequency of occurrence = 0.2
+
+
+_______________________________________________________________________
+Confidence Lower CP Upper CP Lower JP Upper JP
+ Value (%) Limit Limit Limit Limit
+_______________________________________________________________________
+ 50.000 0.12840 0.29588 0.14974 0.26916
+ 75.000 0.09775 0.34633 0.11653 0.31861
+ 90.000 0.07135 0.40103 0.08734 0.37274
+ 95.000 0.05733 0.43661 0.07152 0.40823
+ 99.000 0.03576 0.50661 0.04655 0.47859
+ 99.900 0.01905 0.58632 0.02634 0.55960
+ 99.990 0.01042 0.64997 0.01530 0.62495
+ 99.999 0.00577 0.70216 0.00901 0.67897
+''']
+
+As you can see, even at the 95% confidence level the bounds are
+really quite wide (this example is chosen to be easily compared to the one
+in the __handbook
+[@http://www.itl.nist.gov/div898/handbook/prc/section2/prc241.htm
+here]). Note also that the Clopper-Pearson calculation method (CP above)
+produces quite noticeably more pessimistic estimates than the Jeffreys Prior
+method (JP above).
+
+
+Compare that with the program output for
+2000 trials:
+
+[pre'''___________________________________________
+2-Sided Confidence Limits For Success Ratio
+___________________________________________
+
+Number of Observations = 2000
+Number of successes = 400
+Sample frequency of occurrence = 0.2000000
+
+
+_______________________________________________________________________
+Confidence Lower CP Upper CP Lower JP Upper JP
+ Value (%) Limit Limit Limit Limit
+_______________________________________________________________________
+ 50.000 0.19382 0.20638 0.19406 0.20613
+ 75.000 0.18965 0.21072 0.18990 0.21047
+ 90.000 0.18537 0.21528 0.18561 0.21503
+ 95.000 0.18267 0.21821 0.18291 0.21796
+ 99.000 0.17745 0.22400 0.17769 0.22374
+ 99.900 0.17150 0.23079 0.17173 0.23053
+ 99.990 0.16658 0.23657 0.16681 0.23631
+ 99.999 0.16233 0.24169 0.16256 0.24143
+''']
+
+Now even when the confidence level is very high, the limits are really
+quite close to the experimentally calculated value of 0.2. Furthermore
+the difference between the two calculation methods is now really quite small.
+
+[endsect]
+
+[section:binom_size_eg Estimating Sample Sizes for a Binomial Distribution.]
+
+Imagine you have a critical component that you know will fail in 1 in
+N "uses" (for some suitable definition of "use"). You may want to schedule
+routine replacement of the component so that its chance of failure between
+routine replacements is less than P%. If the failures follow a binomial
+distribution (each time the component is "used" it either fails or does not)
+then the static member function `binomial_distibution<>::find_maximum_number_of_trials`
+can be used to estimate the maximum number of "uses" of that component for some
+acceptable risk level /alpha/.
+
+The example program
+[@../../example/binomial_sample_sizes.cpp binomial_sample_sizes.cpp]
+demonstrates its usage. It centres on a routine that prints out
+a table of maximum sample sizes for various probability thresholds:
+
+ void find_max_sample_size(
+ double p, // success ratio.
+ unsigned successes) // Total number of observed successes permitted.
+ {
+
+The routine then declares a table of probability thresholds: these are the
+maximum acceptable probability that /successes/ or fewer events will be
+observed. In our example, /successes/ will be always zero, since we want
+no component failures, but in other situations non-zero values may well
+make sense.
+
+ double alpha[] = { 0.5, 0.25, 0.1, 0.05, 0.01, 0.001, 0.0001, 0.00001 };
+
+Much of the rest of the program is pretty-printing, the important part
+is in the calculation of maximum number of permitted trials for each
+value of alpha:
+
+ for(unsigned i = 0; i < sizeof(alpha)/sizeof(alpha[0]); ++i)
+ {
+ // Confidence value:
+ cout << fixed << setprecision(3) << setw(10) << right << 100 * (1-alpha[i]);
+ // calculate trials:
+ double t = binomial::find_maximum_number_of_trials(
+ successes, p, alpha[i]);
+ t = floor(t);
+ // Print Trials:
+ cout << fixed << setprecision(5) << setw(15) << right << t << endl;
+ }
+
+Note that since we're
+calculating the maximum number of trials permitted, we'll err on the safe
+side and take the floor of the result. Had we been calculating the
+/minimum/ number of trials required to observe a certain number of /successes/
+using `find_minimum_number_of_trials` we would have taken the ceiling instead.
+
+We'll finish off by looking at some sample output, firstly for
+a 1 in 1000 chance of component failure with each use:
+
+[pre
+'''________________________
+Maximum Number of Trials
+________________________
+
+Success ratio = 0.001
+Maximum Number of "successes" permitted = 0
+
+
+____________________________
+Confidence Max Number
+ Value (%) Of Trials
+____________________________
+ 50.000 692
+ 75.000 287
+ 90.000 105
+ 95.000 51
+ 99.000 10
+ 99.900 0
+ 99.990 0
+ 99.999 0'''
+]
+
+So 51 "uses" of the component would yield a 95% chance that no
+component failures would be observed.
+
+Compare that with a 1 in 1 million chance of component failure:
+
+[pre'''
+________________________
+Maximum Number of Trials
+________________________
+
+Success ratio = 0.0000010
+Maximum Number of "successes" permitted = 0
+
+
+____________________________
+Confidence Max Number
+ Value (%) Of Trials
+____________________________
+ 50.000 693146
+ 75.000 287681
+ 90.000 105360
+ 95.000 51293
+ 99.000 10050
+ 99.900 1000
+ 99.990 100
+ 99.999 10'''
+]
+
+In this case, even 1000 uses of the component would still yield a
+less than 1 in 1000 chance of observing a component failure
+(i.e. a 99.9% chance of no failure).
+
+[endsect] [/section:binom_size_eg Estimating Sample Sizes for a Binomial Distribution.]
+
+[endsect][/section:binom_eg Binomial Distribution]
+
+[/
+ 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).
+]
+
diff --git a/doc/distributions/c_sharp.qbk b/doc/distributions/c_sharp.qbk
new file mode 100644
index 0000000..6764f25
--- /dev/null
+++ b/doc/distributions/c_sharp.qbk
@@ -0,0 +1,20 @@
+[section:c_sharp Using the Distributions from Within C#]
+
+The distributions in this library can be used from the C# programming language
+when they are built using Microsoft's Common Language Runtime (CLR) option.
+
+An example of this kind of usage is given in the
+[@../distexplorer/html/index.html Distribution Explorer]
+example. See =boost-root/libs/math/dot_net_example=
+for the source code: the application consists of a C++ .dll that contains the
+actual distributions, and a C# GUI that allows you to explore their properties.
+
+[endsect] [/section:c_sharp]
+
+[/
+ Copyright 2006, 2013 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).
+]
+
diff --git a/doc/distributions/cauchy.qbk b/doc/distributions/cauchy.qbk
new file mode 100644
index 0000000..e91ebe2
--- /dev/null
+++ b/doc/distributions/cauchy.qbk
@@ -0,0 +1,154 @@
+[section:cauchy_dist Cauchy-Lorentz Distribution]
+
+``#include <boost/math/distributions/cauchy.hpp>``
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class cauchy_distribution;
+
+ typedef cauchy_distribution<> cauchy;
+
+ template <class RealType, class ``__Policy``>
+ class cauchy_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ cauchy_distribution(RealType location = 0, RealType scale = 1);
+
+ RealType location()const;
+ RealType scale()const;
+ };
+
+The [@http://en.wikipedia.org/wiki/Cauchy_distribution Cauchy-Lorentz distribution]
+is named after Augustin Cauchy and Hendrik Lorentz.
+It is a [@http://en.wikipedia.org/wiki/Probability_distribution continuous probability distribution]
+with [@http://en.wikipedia.org/wiki/Probability_distribution probability distribution function PDF]
+given by:
+
+[equation cauchy_ref1]
+
+The location parameter x[sub 0][space] is the location of the
+peak of the distribution (the mode of the distribution),
+while the scale parameter [gamma][space] specifies half the width
+of the PDF at half the maximum height. If the location is
+zero, and the scale 1, then the result is a standard Cauchy
+distribution.
+
+The distribution is important in physics as it is the solution
+to the differential equation describing forced resonance,
+while in spectroscopy it is the description of the line shape
+of spectral lines.
+
+The following graph shows how the distributions moves as the
+location parameter changes:
+
+[graph cauchy_pdf1]
+
+While the following graph shows how the shape (scale) parameter alters
+the distribution:
+
+[graph cauchy_pdf2]
+
+[h4 Member Functions]
+
+ cauchy_distribution(RealType location = 0, RealType scale = 1);
+
+Constructs a Cauchy distribution, with location parameter /location/
+and scale parameter /scale/. When these parameters take their default
+values (location = 0, scale = 1)
+then the result is a Standard Cauchy Distribution.
+
+Requires scale > 0, otherwise calls __domain_error.
+
+ RealType location()const;
+
+Returns the location parameter of the distribution.
+
+ RealType scale()const;
+
+Returns the scale parameter of the distribution.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
+that are generic to all distributions are supported: __usual_accessors.
+
+Note however that the Cauchy distribution does not have a mean,
+standard deviation, etc. See __math_undefined
+[/link math_toolkit.pol_ref.assert_undefined mathematically undefined function]
+to control whether these should fail to compile with a BOOST_STATIC_ASSERTION_FAILURE,
+which is the default.
+
+Alternately, the functions __mean, __sd,
+__variance, __skewness, __kurtosis and __kurtosis_excess will all
+return a __domain_error if called.
+
+The domain of the random variable is \[-[max_value], +[min_value]\].
+
+[h4 Accuracy]
+
+The Cauchy distribution is implemented in terms of the
+standard library `tan` and `atan` functions,
+and as such should have very low error rates.
+
+[h4 Implementation]
+
+[def __x0 x[sub 0 ]]
+
+In the following table __x0 is the location parameter of the distribution,
+[gamma][space] is its scale parameter,
+/x/ is the random variate, /p/ is the probability and /q = 1-p/.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Using the relation: pdf = 1 / ([pi] * [gamma] * (1 + ((x - __x0) / [gamma])[super 2]) ]]
+[[cdf and its complement][
+The cdf is normally given by:
+
+p = 0.5 + atan(x)/[pi]
+
+But that suffers from cancellation error as x -> -[infin].
+So recall that for `x < 0`:
+
+atan(x) = -[pi]/2 - atan(1/x)
+
+Substituting into the above we get:
+
+p = -atan(1/x) ; x < 0
+
+So the procedure is to calculate the cdf for -fabs(x)
+using the above formula. Note that to factor in the location and scale
+parameters you must substitute (x - __x0) / [gamma][space] for x in the above.
+
+This procedure yields the smaller of /p/ and /q/, so the result
+may need subtracting from 1 depending on whether we want the complement
+or not, and whether /x/ is less than __x0 or not.
+]]
+[[quantile][The same procedure is used irrespective of whether we're starting
+ from the probability or its complement. First the argument /p/ is
+ reduced to the range \[-0.5, 0.5\], then the relation
+
+x = __x0 [plusminus] [gamma][space] / tan([pi] * p)
+
+is used to obtain the result. Whether we're adding
+ or subtracting from __x0 is determined by whether we're
+ starting from the complement or not.]]
+[[mode][The location parameter.]]
+]
+
+[h4 References]
+
+* [@http://en.wikipedia.org/wiki/Cauchy_distribution Cauchy-Lorentz distribution]
+* [@http://www.itl.nist.gov/div898/handbook/eda/section3/eda3663.htm NIST Exploratory Data Analysis]
+* [@http://mathworld.wolfram.com/CauchyDistribution.html Weisstein, Eric W. "Cauchy Distribution." From MathWorld--A Wolfram Web Resource.]
+
+[endsect][/section:cauchy_dist Cauchi]
+
+[/ cauchy.qbk
+ Copyright 2006, 2007 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).
+]
diff --git a/doc/distributions/chi_squared.qbk b/doc/distributions/chi_squared.qbk
new file mode 100644
index 0000000..77237e0
--- /dev/null
+++ b/doc/distributions/chi_squared.qbk
@@ -0,0 +1,161 @@
+[section:chi_squared_dist Chi Squared Distribution]
+
+``#include <boost/math/distributions/chi_squared.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class chi_squared_distribution;
+
+ typedef chi_squared_distribution<> chi_squared;
+
+ template <class RealType, class ``__Policy``>
+ class chi_squared_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ // Constructor:
+ chi_squared_distribution(RealType i);
+
+ // Accessor to parameter:
+ RealType degrees_of_freedom()const;
+
+ // Parameter estimation:
+ static RealType find_degrees_of_freedom(
+ RealType difference_from_mean,
+ RealType alpha,
+ RealType beta,
+ RealType sd,
+ RealType hint = 100);
+ };
+
+ }} // namespaces
+
+The Chi-Squared distribution is one of the most widely used distributions
+in statistical tests. If [chi][sub i][space] are [nu][space]
+independent, normally distributed
+random variables with means [mu][sub i][space] and variances [sigma][sub i][super 2],
+then the random variable:
+
+[equation chi_squ_ref1]
+
+is distributed according to the Chi-Squared distribution.
+
+The Chi-Squared distribution is a special case of the gamma distribution
+and has a single parameter [nu][space] that specifies the number of degrees of
+freedom. The following graph illustrates how the distribution changes
+for different values of [nu]:
+
+[graph chi_squared_pdf]
+
+[h4 Member Functions]
+
+ chi_squared_distribution(RealType v);
+
+Constructs a Chi-Squared distribution with /v/ degrees of freedom.
+
+Requires v > 0, otherwise calls __domain_error.
+
+ RealType degrees_of_freedom()const;
+
+Returns the parameter /v/ from which this object was constructed.
+
+ static RealType find_degrees_of_freedom(
+ RealType difference_from_variance,
+ RealType alpha,
+ RealType beta,
+ RealType variance,
+ RealType hint = 100);
+
+Estimates the sample size required to detect a difference from a nominal
+variance in a Chi-Squared test for equal standard deviations.
+
+[variablelist
+[[difference_from_variance][The difference from the assumed nominal variance
+ that is to be detected: Note that the sign of this value is critical, see below.]]
+[[alpha][The maximum acceptable risk of rejecting the null hypothesis when it is
+ in fact true.]]
+[[beta][The maximum acceptable risk of falsely failing to reject the null hypothesis.]]
+[[variance][The nominal variance being tested against.]]
+[[hint][An optional hint on where to start looking for a result: the current sample
+ size would be a good choice.]]
+]
+
+Note that this calculation works with /variances/ and not /standard deviations/.
+
+The sign of the parameter /difference_from_variance/ is important: the Chi
+Squared distribution is asymmetric, and the caller must decide in advance
+whether they are testing for a variance greater than a nominal value (positive
+/difference_from_variance/) or testing for a variance less than a nominal value
+(negative /difference_from_variance/). If the latter, then obviously it is
+a requirement that `variance + difference_from_variance > 0`, since no sample
+can have a negative variance!
+
+This procedure uses the method in Diamond, W. J. (1989).
+Practical Experiment Designs, Van-Nostrand Reinhold, New York.
+
+See also section on Sample sizes required in
+[@http://www.itl.nist.gov/div898/handbook/prc/section2/prc232.htm the NIST Engineering Statistics Handbook, Section 7.2.3.2].
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
+that are generic to all distributions are supported: __usual_accessors.
+
+(We have followed the usual restriction of the mode to degrees of freedom >= 2,
+but note that the maximum of the pdf is actually zero for degrees of freedom from 2 down to 0,
+and provide an extended definition that would avoid a discontinuity in the mode
+as alternative code in a comment).
+
+The domain of the random variable is \[0, +[infin]\].
+
+[h4 Examples]
+
+Various [link math_toolkit.stat_tut.weg.cs_eg worked examples]
+are available illustrating the use of the Chi Squared Distribution.
+
+[h4 Accuracy]
+
+The Chi-Squared distribution is implemented in terms of the
+[link math_toolkit.sf_gamma.igamma incomplete gamma functions]:
+please refer to the accuracy data for those functions.
+
+[h4 Implementation]
+
+In the following table /v/ is the number of degrees of freedom of the distribution,
+/x/ is the random variate, /p/ is the probability, and /q = 1-p/.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Using the relation: pdf = __gamma_p_derivative(v / 2, x / 2) / 2 ]]
+[[cdf][Using the relation: p = __gamma_p(v / 2, x / 2) ]]
+[[cdf complement][Using the relation: q = __gamma_q(v / 2, x / 2) ]]
+[[quantile][Using the relation: x = 2 * __gamma_p_inv(v / 2, p) ]]
+[[quantile from the complement][Using the relation: x = 2 * __gamma_q_inv(v / 2, p) ]]
+[[mean][v]]
+[[variance][2v]]
+[[mode][v - 2 (if v >= 2)]]
+[[skewness][2 * sqrt(2 / v) == sqrt(8 / v)]]
+[[kurtosis][3 + 12 / v]]
+[[kurtosis excess][12 / v]]
+]
+
+[h4 References]
+
+* [@http://www.itl.nist.gov/div898/handbook/eda/section3/eda3666.htm NIST Exploratory Data Analysis]
+* [@http://en.wikipedia.org/wiki/Chi-square_distribution Chi-square distribution]
+* [@http://mathworld.wolfram.com/Chi-SquaredDistribution.html Weisstein, Eric W. "Chi-Squared Distribution." From MathWorld--A Wolfram Web Resource.]
+
+
+[endsect][/section:chi_squared_dist Chi Squared]
+
+[/ chi_squared.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).
+]
+
diff --git a/doc/distributions/chi_squared_examples.qbk b/doc/distributions/chi_squared_examples.qbk
new file mode 100644
index 0000000..8f01585
--- /dev/null
+++ b/doc/distributions/chi_squared_examples.qbk
@@ -0,0 +1,500 @@
+
+[section:cs_eg Chi Squared Distribution Examples]
+
+[section:chi_sq_intervals Confidence Intervals on the Standard Deviation]
+
+Once you have calculated the standard deviation for your data, a legitimate
+question to ask is "How reliable is the calculated standard deviation?".
+For this situation the Chi Squared distribution can be used to calculate
+confidence intervals for the standard deviation.
+
+The full example code & sample output is in
+[@../../example/chi_square_std_dev_test.cpp chi_square_std_dev_test.cpp].
+
+We'll begin by defining the procedure that will calculate and print out the
+confidence intervals:
+
+ void confidence_limits_on_std_deviation(
+ double Sd, // Sample Standard Deviation
+ unsigned N) // Sample size
+ {
+
+We'll begin by printing out some general information:
+
+ cout <<
+ "________________________________________________\n"
+ "2-Sided Confidence Limits For Standard Deviation\n"
+ "________________________________________________\n\n";
+ cout << setprecision(7);
+ cout << setw(40) << left << "Number of Observations" << "= " << N << "\n";
+ cout << setw(40) << left << "Standard Deviation" << "= " << Sd << "\n";
+
+and then define a table of significance levels for which we'll calculate
+intervals:
+
+ double alpha[] = { 0.5, 0.25, 0.1, 0.05, 0.01, 0.001, 0.0001, 0.00001 };
+
+The distribution we'll need to calculate the confidence intervals is a
+Chi Squared distribution, with N-1 degrees of freedom:
+
+ chi_squared dist(N - 1);
+
+For each value of alpha, the formula for the confidence interval is given by:
+
+[equation chi_squ_tut1]
+
+Where [equation chi_squ_tut2] is the upper critical value, and
+[equation chi_squ_tut3] is the lower critical value of the
+Chi Squared distribution.
+
+In code we begin by printing out a table header:
+
+ cout << "\n\n"
+ "_____________________________________________\n"
+ "Confidence Lower Upper\n"
+ " Value (%) Limit Limit\n"
+ "_____________________________________________\n";
+
+and then loop over the values of alpha and calculate the intervals
+for each: remember that the lower critical value is the same as the
+quantile, and the upper critical value is the same as the quantile
+from the complement of the probability:
+
+ for(unsigned i = 0; i < sizeof(alpha)/sizeof(alpha[0]); ++i)
+ {
+ // Confidence value:
+ cout << fixed << setprecision(3) << setw(10) << right << 100 * (1-alpha[i]);
+ // Calculate limits:
+ double lower_limit = sqrt((N - 1) * Sd * Sd / quantile(complement(dist, alpha[i] / 2)));
+ double upper_limit = sqrt((N - 1) * Sd * Sd / quantile(dist, alpha[i] / 2));
+ // Print Limits:
+ cout << fixed << setprecision(5) << setw(15) << right << lower_limit;
+ cout << fixed << setprecision(5) << setw(15) << right << upper_limit << endl;
+ }
+ cout << endl;
+
+To see some example output we'll use the
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda3581.htm
+gear data] from the __handbook.
+The data represents measurements of gear diameter from a manufacturing
+process.
+
+[pre'''
+________________________________________________
+2-Sided Confidence Limits For Standard Deviation
+________________________________________________
+
+Number of Observations = 100
+Standard Deviation = 0.006278908
+
+
+_____________________________________________
+Confidence Lower Upper
+ Value (%) Limit Limit
+_____________________________________________
+ 50.000 0.00601 0.00662
+ 75.000 0.00582 0.00685
+ 90.000 0.00563 0.00712
+ 95.000 0.00551 0.00729
+ 99.000 0.00530 0.00766
+ 99.900 0.00507 0.00812
+ 99.990 0.00489 0.00855
+ 99.999 0.00474 0.00895
+''']
+
+So at the 95% confidence level we conclude that the standard deviation
+is between 0.00551 and 0.00729.
+
+[h4 Confidence intervals as a function of the number of observations]
+
+Similarly, we can also list the confidence intervals for the standard deviation
+for the common confidence levels 95%, for increasing numbers of observations.
+
+The standard deviation used to compute these values is unity,
+so the limits listed are *multipliers* for any particular standard deviation.
+For example, given a standard deviation of 0.0062789 as in the example
+above; for 100 observations the multiplier is 0.8780
+giving the lower confidence limit of 0.8780 * 0.006728 = 0.00551.
+
+[pre'''
+____________________________________________________
+Confidence level (two-sided) = 0.0500000
+Standard Deviation = 1.0000000
+________________________________________
+Observations Lower Upper
+ Limit Limit
+________________________________________
+ 2 0.4461 31.9102
+ 3 0.5207 6.2847
+ 4 0.5665 3.7285
+ 5 0.5991 2.8736
+ 6 0.6242 2.4526
+ 7 0.6444 2.2021
+ 8 0.6612 2.0353
+ 9 0.6755 1.9158
+ 10 0.6878 1.8256
+ 15 0.7321 1.5771
+ 20 0.7605 1.4606
+ 30 0.7964 1.3443
+ 40 0.8192 1.2840
+ 50 0.8353 1.2461
+ 60 0.8476 1.2197
+ 100 0.8780 1.1617
+ 120 0.8875 1.1454
+ 1000 0.9580 1.0459
+ 10000 0.9863 1.0141
+ 50000 0.9938 1.0062
+ 100000 0.9956 1.0044
+ 1000000 0.9986 1.0014
+''']
+
+With just 2 observations the limits are from *0.445* up to to *31.9*,
+so the standard deviation might be about *half*
+the observed value up to [*30 times] the observed value!
+
+Estimating a standard deviation with just a handful of values leaves a very great uncertainty,
+especially the upper limit.
+Note especially how far the upper limit is skewed from the most likely standard deviation.
+
+Even for 10 observations, normally considered a reasonable number,
+the range is still from 0.69 to 1.8, about a range of 0.7 to 2,
+and is still highly skewed with an upper limit *twice* the median.
+
+When we have 1000 observations, the estimate of the standard deviation is starting to look convincing,
+with a range from 0.95 to 1.05 - now near symmetrical, but still about + or - 5%.
+
+Only when we have 10000 or more repeated observations can we start to be reasonably confident
+(provided we are sure that other factors like drift are not creeping in).
+
+For 10000 observations, the interval is 0.99 to 1.1 - finally a really convincing + or -1% confidence.
+
+[endsect] [/section:chi_sq_intervals Confidence Intervals on the Standard Deviation]
+
+[section:chi_sq_test Chi-Square Test for the Standard Deviation]
+
+We use this test to determine whether the standard deviation of a sample
+differs from a specified value. Typically this occurs in process change
+situations where we wish to compare the standard deviation of a new
+process to an established one.
+
+The code for this example is contained in
+[@../../example/chi_square_std_dev_test.cpp chi_square_std_dev_test.cpp], and
+we'll begin by defining the procedure that will print out the test
+statistics:
+
+ void chi_squared_test(
+ double Sd, // Sample std deviation
+ double D, // True std deviation
+ unsigned N, // Sample size
+ double alpha) // Significance level
+ {
+
+The procedure begins by printing a summary of the input data:
+
+ using namespace std;
+ using namespace boost::math;
+
+ // Print header:
+ cout <<
+ "______________________________________________\n"
+ "Chi Squared test for sample standard deviation\n"
+ "______________________________________________\n\n";
+ cout << setprecision(5);
+ cout << setw(55) << left << "Number of Observations" << "= " << N << "\n";
+ cout << setw(55) << left << "Sample Standard Deviation" << "= " << Sd << "\n";
+ cout << setw(55) << left << "Expected True Standard Deviation" << "= " << D << "\n\n";
+
+The test statistic (T) is simply the ratio of the sample and "true" standard
+deviations squared, multiplied by the number of degrees of freedom (the
+sample size less one):
+
+ double t_stat = (N - 1) * (Sd / D) * (Sd / D);
+ cout << setw(55) << left << "Test Statistic" << "= " << t_stat << "\n";
+
+The distribution we need to use, is a Chi Squared distribution with N-1
+degrees of freedom:
+
+ chi_squared dist(N - 1);
+
+The various hypothesis that can be tested are summarised in the following table:
+
+[table
+[[Hypothesis][Test]]
+[[The null-hypothesis: there is no difference in standard deviation from the specified value]
+ [ Reject if T < [chi][super 2][sub (1-alpha/2; N-1)] or T > [chi][super 2][sub (alpha/2; N-1)] ]]
+[[The alternative hypothesis: there is a difference in standard deviation from the specified value]
+ [ Reject if [chi][super 2][sub (1-alpha/2; N-1)] >= T >= [chi][super 2][sub (alpha/2; N-1)] ]]
+[[The alternative hypothesis: the standard deviation is less than the specified value]
+ [ Reject if [chi][super 2][sub (1-alpha; N-1)] <= T ]]
+[[The alternative hypothesis: the standard deviation is greater than the specified value]
+ [ Reject if [chi][super 2][sub (alpha; N-1)] >= T ]]
+]
+
+Where [chi][super 2][sub (alpha; N-1)] is the upper critical value of the
+Chi Squared distribution, and [chi][super 2][sub (1-alpha; N-1)] is the
+lower critical value.
+
+Recall that the lower critical value is the same
+as the quantile, and the upper critical value is the same as the quantile
+from the complement of the probability, that gives us the following code
+to calculate the critical values:
+
+ double ucv = quantile(complement(dist, alpha));
+ double ucv2 = quantile(complement(dist, alpha / 2));
+ double lcv = quantile(dist, alpha);
+ double lcv2 = quantile(dist, alpha / 2);
+ cout << setw(55) << left << "Upper Critical Value at alpha: " << "= "
+ << setprecision(3) << scientific << ucv << "\n";
+ cout << setw(55) << left << "Upper Critical Value at alpha/2: " << "= "
+ << setprecision(3) << scientific << ucv2 << "\n";
+ cout << setw(55) << left << "Lower Critical Value at alpha: " << "= "
+ << setprecision(3) << scientific << lcv << "\n";
+ cout << setw(55) << left << "Lower Critical Value at alpha/2: " << "= "
+ << setprecision(3) << scientific << lcv2 << "\n\n";
+
+Now that we have the critical values, we can compare these to our test
+statistic, and print out the result of each hypothesis and test:
+
+ cout << setw(55) << left <<
+ "Results for Alternative Hypothesis and alpha" << "= "
+ << setprecision(4) << fixed << alpha << "\n\n";
+ cout << "Alternative Hypothesis Conclusion\n";
+
+ cout << "Standard Deviation != " << setprecision(3) << fixed << D << " ";
+ if((ucv2 < t_stat) || (lcv2 > t_stat))
+ cout << "ACCEPTED\n";
+ else
+ cout << "REJECTED\n";
+
+ cout << "Standard Deviation < " << setprecision(3) << fixed << D << " ";
+ if(lcv > t_stat)
+ cout << "ACCEPTED\n";
+ else
+ cout << "REJECTED\n";
+
+ cout << "Standard Deviation > " << setprecision(3) << fixed << D << " ";
+ if(ucv < t_stat)
+ cout << "ACCEPTED\n";
+ else
+ cout << "REJECTED\n";
+ cout << endl << endl;
+
+To see some example output we'll use the
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda3581.htm
+gear data] from the __handbook.
+The data represents measurements of gear diameter from a manufacturing
+process. The program output is deliberately designed to mirror
+the DATAPLOT output shown in the
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda358.htm
+NIST Handbook Example].
+
+[pre'''
+______________________________________________
+Chi Squared test for sample standard deviation
+______________________________________________
+
+Number of Observations = 100
+Sample Standard Deviation = 0.00628
+Expected True Standard Deviation = 0.10000
+
+Test Statistic = 0.39030
+CDF of test statistic: = 1.438e-099
+Upper Critical Value at alpha: = 1.232e+002
+Upper Critical Value at alpha/2: = 1.284e+002
+Lower Critical Value at alpha: = 7.705e+001
+Lower Critical Value at alpha/2: = 7.336e+001
+
+Results for Alternative Hypothesis and alpha = 0.0500
+
+Alternative Hypothesis Conclusion'''
+Standard Deviation != 0.100 ACCEPTED
+Standard Deviation < 0.100 ACCEPTED
+Standard Deviation > 0.100 REJECTED
+]
+
+In this case we are testing whether the sample standard deviation is 0.1,
+and the null-hypothesis is rejected, so we conclude that the standard
+deviation ['is not] 0.1.
+
+For an alternative example, consider the
+[@http://www.itl.nist.gov/div898/handbook/prc/section2/prc23.htm
+silicon wafer data] again from the __handbook.
+In this scenario a supplier of 100 ohm.cm silicon wafers claims
+that his fabrication process can produce wafers with sufficient
+consistency so that the standard deviation of resistivity for
+the lot does not exceed 10 ohm.cm. A sample of N = 10 wafers taken
+from the lot has a standard deviation of 13.97 ohm.cm, and the question
+we ask ourselves is "Is the suppliers claim correct?".
+
+The program output now looks like this:
+
+[pre'''
+______________________________________________
+Chi Squared test for sample standard deviation
+______________________________________________
+
+Number of Observations = 10
+Sample Standard Deviation = 13.97000
+Expected True Standard Deviation = 10.00000
+
+Test Statistic = 17.56448
+CDF of test statistic: = 9.594e-001
+Upper Critical Value at alpha: = 1.692e+001
+Upper Critical Value at alpha/2: = 1.902e+001
+Lower Critical Value at alpha: = 3.325e+000
+Lower Critical Value at alpha/2: = 2.700e+000
+
+Results for Alternative Hypothesis and alpha = 0.0500
+
+Alternative Hypothesis Conclusion'''
+Standard Deviation != 10.000 REJECTED
+Standard Deviation < 10.000 REJECTED
+Standard Deviation > 10.000 ACCEPTED
+]
+
+In this case, our null-hypothesis is that the standard deviation of
+the sample is less than 10: this hypothesis is rejected in the analysis
+above, and so we reject the manufacturers claim.
+
+[endsect] [/section:chi_sq_test Chi-Square Test for the Standard Deviation]
+
+[section:chi_sq_size Estimating the Required Sample Sizes for a Chi-Square Test for the Standard Deviation]
+
+Suppose we conduct a Chi Squared test for standard deviation and the result
+is borderline, a legitimate question to ask is "How large would the sample size
+have to be in order to produce a definitive result?"
+
+The class template [link math_toolkit.dist_ref.dists.chi_squared_dist
+chi_squared_distribution] has a static method
+`find_degrees_of_freedom` that will calculate this value for
+some acceptable risk of type I failure /alpha/, type II failure
+/beta/, and difference from the standard deviation /diff/. Please
+note that the method used works on variance, and not standard deviation
+as is usual for the Chi Squared Test.
+
+The code for this example is located in
+[@../../example/chi_square_std_dev_test.cpp chi_square_std_dev_test.cpp].
+
+We begin by defining a procedure to print out the sample sizes required
+for various risk levels:
+
+ void chi_squared_sample_sized(
+ double diff, // difference from variance to detect
+ double variance) // true variance
+ {
+
+The procedure begins by printing out the input data:
+
+ using namespace std;
+ using namespace boost::math;
+
+ // Print out general info:
+ cout <<
+ "_____________________________________________________________\n"
+ "Estimated sample sizes required for various confidence levels\n"
+ "_____________________________________________________________\n\n";
+ cout << setprecision(5);
+ cout << setw(40) << left << "True Variance" << "= " << variance << "\n";
+ cout << setw(40) << left << "Difference to detect" << "= " << diff << "\n";
+
+And defines a table of significance levels for which we'll calculate sample sizes:
+
+ double alpha[] = { 0.5, 0.25, 0.1, 0.05, 0.01, 0.001, 0.0001, 0.00001 };
+
+For each value of alpha we can calculate two sample sizes: one where the
+sample variance is less than the true value by /diff/ and one
+where it is greater than the true value by /diff/. Thanks to the
+asymmetric nature of the Chi Squared distribution these two values will
+not be the same, the difference in their calculation differs only in the
+sign of /diff/ that's passed to `find_degrees_of_freedom`. Finally
+in this example we'll simply things, and let risk level /beta/ be the
+same as /alpha/:
+
+ cout << "\n\n"
+ "_______________________________________________________________\n"
+ "Confidence Estimated Estimated\n"
+ " Value (%) Sample Size Sample Size\n"
+ " (lower one (upper one\n"
+ " sided test) sided test)\n"
+ "_______________________________________________________________\n";
+ //
+ // Now print out the data for the table rows.
+ //
+ for(unsigned i = 0; i < sizeof(alpha)/sizeof(alpha[0]); ++i)
+ {
+ // Confidence value:
+ cout << fixed << setprecision(3) << setw(10) << right << 100 * (1-alpha[i]);
+ // calculate df for a lower single sided test:
+ double df = chi_squared::find_degrees_of_freedom(
+ -diff, alpha[i], alpha[i], variance);
+ // convert to sample size:
+ double size = ceil(df) + 1;
+ // Print size:
+ cout << fixed << setprecision(0) << setw(16) << right << size;
+ // calculate df for an upper single sided test:
+ df = chi_squared::find_degrees_of_freedom(
+ diff, alpha[i], alpha[i], variance);
+ // convert to sample size:
+ size = ceil(df) + 1;
+ // Print size:
+ cout << fixed << setprecision(0) << setw(16) << right << size << endl;
+ }
+ cout << endl;
+
+For some example output, consider the
+[@http://www.itl.nist.gov/div898/handbook/prc/section2/prc23.htm
+silicon wafer data] from the __handbook.
+In this scenario a supplier of 100 ohm.cm silicon wafers claims
+that his fabrication process can produce wafers with sufficient
+consistency so that the standard deviation of resistivity for
+the lot does not exceed 10 ohm.cm. A sample of N = 10 wafers taken
+from the lot has a standard deviation of 13.97 ohm.cm, and the question
+we ask ourselves is "How large would our sample have to be to reliably
+detect this difference?".
+
+To use our procedure above, we have to convert the
+standard deviations to variance (square them),
+after which the program output looks like this:
+
+[pre'''
+_____________________________________________________________
+Estimated sample sizes required for various confidence levels
+_____________________________________________________________
+
+True Variance = 100.00000
+Difference to detect = 95.16090
+
+
+_______________________________________________________________
+Confidence Estimated Estimated
+ Value (%) Sample Size Sample Size
+ (lower one (upper one
+ sided test) sided test)
+_______________________________________________________________
+ 50.000 2 2
+ 75.000 2 10
+ 90.000 4 32
+ 95.000 5 51
+ 99.000 7 99
+ 99.900 11 174
+ 99.990 15 251
+ 99.999 20 330'''
+]
+
+In this case we are interested in a upper single sided test.
+So for example, if the maximum acceptable risk of falsely rejecting
+the null-hypothesis is 0.05 (Type I error), and the maximum acceptable
+risk of failing to reject the null-hypothesis is also 0.05
+(Type II error), we estimate that we would need a sample size of 51.
+
+[endsect] [/section:chi_sq_size Estimating the Required Sample Sizes for a Chi-Square Test for the Standard Deviation]
+
+[endsect] [/section:cs_eg Chi Squared Distribution]
+
+[/
+ Copyright 2006, 2013 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).
+]
+
diff --git a/doc/distributions/dist_algorithms.qbk b/doc/distributions/dist_algorithms.qbk
new file mode 100644
index 0000000..a29daee
--- /dev/null
+++ b/doc/distributions/dist_algorithms.qbk
@@ -0,0 +1,78 @@
+[section:dist_algorithms Distribution Algorithms]
+
+[h4 Finding the Location and Scale for Normal and similar distributions]
+
+Two functions aid finding location and scale of random variable z
+to give probability p (given a scale or location).
+Only applies to distributions like normal, lognormal, extreme value, Cauchy, (and symmetrical triangular),
+that have scale and location properties.
+
+These functions are useful to predict the mean and/or standard deviation that will be needed to meet a specified minimum weight or maximum dose.
+
+Complement versions are also provided, both with explicit and implicit (default) policy.
+
+ using boost::math::policies::policy; // May be needed by users defining their own policies.
+ using boost::math::complement; // Will be needed by users who want to use complements.
+
+[h4 find_location function]
+
+``#include <boost/math/distributions/find_location.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class Dist, class ``__Policy``> // explicit error handling policy
+ typename Dist::value_type find_location( // For example, normal mean.
+ typename Dist::value_type z, // location of random variable z to give probability, P(X > z) == p.
+ // For example, a nominal minimum acceptable z, so that p * 100 % are > z
+ typename Dist::value_type p, // probability value desired at x, say 0.95 for 95% > z.
+ typename Dist::value_type scale, // scale parameter, for example, normal standard deviation.
+ const ``__Policy``& pol);
+
+ template <class Dist> // with default policy.
+ typename Dist::value_type find_location( // For example, normal mean.
+ typename Dist::value_type z, // location of random variable z to give probability, P(X > z) == p.
+ // For example, a nominal minimum acceptable z, so that p * 100 % are > z
+ typename Dist::value_type p, // probability value desired at x, say 0.95 for 95% > z.
+ typename Dist::value_type scale); // scale parameter, for example, normal standard deviation.
+
+ }} // namespaces
+
+[h4 find_scale function]
+
+``#include <boost/math/distributions/find_scale.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class Dist, class ``__Policy``>
+ typename Dist::value_type find_scale( // For example, normal mean.
+ typename Dist::value_type z, // location of random variable z to give probability, P(X > z) == p.
+ // For example, a nominal minimum acceptable weight z, so that p * 100 % are > z
+ typename Dist::value_type p, // probability value desired at x, say 0.95 for 95% > z.
+ typename Dist::value_type location, // location parameter, for example, normal distribution mean.
+ const ``__Policy``& pol);
+
+ template <class Dist> // with default policy.
+ typename Dist::value_type find_scale( // For example, normal mean.
+ typename Dist::value_type z, // location of random variable z to give probability, P(X > z) == p.
+ // For example, a nominal minimum acceptable z, so that p * 100 % are > z
+ typename Dist::value_type p, // probability value desired at x, say 0.95 for 95% > z.
+ typename Dist::value_type location) // location parameter, for example, normal distribution mean.
+ }} // namespaces
+
+All argument must be finite, otherwise __domain_error is called.
+
+Probability arguments must be [0, 1], otherwise __domain_error is called.
+
+If the choice of arguments would give a negative scale, __domain_error is called, unless the policy is to ignore, when the negative (impossible) value of scale is returned.
+
+[link math_toolkit.stat_tut.weg.find_eg Find Mean and standard deviation examples]
+gives simple examples of use of both find_scale and find_location, and a longer example finding means and standard deviations of normally distributed weights to meet a specification.
+
+[endsect] [/section:dist_algorithms dist_algorithms]
+
+[/ dist_algorithms.qbk
+ Copyright 2007 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).
+]
diff --git a/doc/distributions/dist_reference.qbk b/doc/distributions/dist_reference.qbk
new file mode 100644
index 0000000..3d5d82f
--- /dev/null
+++ b/doc/distributions/dist_reference.qbk
@@ -0,0 +1,147 @@
+[section:dist_ref Statistical Distributions Reference]
+
+[include non_members.qbk]
+
+[section:dists Distributions]
+
+[include arcsine.qbk]
+[include bernoulli.qbk]
+[include beta.qbk]
+[include binomial.qbk]
+[include cauchy.qbk]
+[include chi_squared.qbk]
+[include exponential.qbk]
+[include extreme_value.qbk]
+[include fisher.qbk]
+[include gamma.qbk]
+[include geometric.qbk]
+[include hyperexponential.qbk]
+[include hypergeometric.qbk]
+[include inverse_chi_squared.qbk]
+[include inverse_gamma.qbk]
+[include inverse_gaussian.qbk]
+[include laplace.qbk]
+[include logistic.qbk]
+[include lognormal.qbk]
+[include negative_binomial.qbk]
+[include nc_beta.qbk]
+[include nc_chi_squared.qbk]
+[include nc_f.qbk]
+[include nc_t.qbk]
+[include normal.qbk]
+[include pareto.qbk]
+[include poisson.qbk]
+[include rayleigh.qbk]
+[include skew_normal.qbk]
+[include students_t.qbk]
+[include triangular.qbk]
+[include uniform.qbk]
+[include weibull.qbk]
+
+[endsect] [/section:dists Distributions]
+
+[include dist_algorithms.qbk]
+
+[endsect] [/section:dist_ref Statistical Distributions and Functions Reference]
+
+
+[section:future Extras/Future Directions]
+
+[h4 Adding Additional Location and Scale Parameters]
+
+In some modelling applications we require a distribution
+with a specific location and scale:
+often this equates to a specific mean and standard deviation, although for many
+distributions the relationship between these properties and the location and
+scale parameters are non-trivial. See
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm]
+for more information.
+
+The obvious way to handle this is via an adapter template:
+
+ template <class Dist>
+ class scaled_distribution
+ {
+ scaled_distribution(
+ const Dist dist,
+ typename Dist::value_type location,
+ typename Dist::value_type scale = 0);
+ };
+
+Which would then have its own set of overloads for the non-member accessor functions.
+
+[h4 An "any_distribution" class]
+
+It is easy to add a distribution object that virtualises
+the actual type of the distribution, and can therefore hold "any" object
+that conforms to the conceptual requirements of a distribution:
+
+ template <class RealType>
+ class any_distribution
+ {
+ public:
+ template <class Distribution>
+ any_distribution(const Distribution& d);
+ };
+
+ // Get the cdf of the underlying distribution:
+ template <class RealType>
+ RealType cdf(const any_distribution<RealType>& d, RealType x);
+ // etc....
+
+Such a class would facilitate the writing of non-template code that can
+function with any distribution type.
+
+The [@http://sourceforge.net/projects/distexplorer/ Statistical Distribution Explorer]
+utility for Windows is a usage example.
+
+It's not clear yet whether there is a compelling use case though.
+Possibly tests for goodness of fit might
+provide such a use case: this needs more investigation.
+
+[h4 Higher Level Hypothesis Tests]
+
+Higher-level tests roughly corresponding to the
+[@http://documents.wolfram.com/mathematica/Add-onsLinks/StandardPackages/Statistics/HypothesisTests.html Mathematica Hypothesis Tests]
+package could be added reasonably easily, for example:
+
+ template <class InputIterator>
+ typename std::iterator_traits<InputIterator>::value_type
+ test_equal_mean(
+ InputIterator a,
+ InputIterator b,
+ typename std::iterator_traits<InputIterator>::value_type expected_mean);
+
+Returns the probability that the data in the sequence \[a,b) has the mean
+/expected_mean/.
+
+[h4 Integration With Statistical Accumulators]
+
+[@http://boost-sandbox.sourceforge.net/libs/accumulators/doc/html/index.html
+Eric Niebler's accumulator framework] - also work in progress - provides the means
+to calculate various statistical properties from experimental data. There is an
+opportunity to integrate the statistical tests with this framework at some later date:
+
+ // Define an accumulator, all required statistics to calculate the test
+ // are calculated automatically:
+ accumulator_set<double, features<tag::test_expected_mean> > acc(expected_mean=4);
+ // Pass our data to the accumulator:
+ acc = std::for_each(mydata.begin(), mydata.end(), acc);
+ // Extract the result:
+ double p = probability(acc);
+
+[endsect] [/section:future Extras Future Directions]
+
+[/ dist_reference.qbk
+ Copyright 2006, 2010 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).
+]
+
+
+
+
+
+
+
diff --git a/doc/distributions/dist_tutorial.qbk b/doc/distributions/dist_tutorial.qbk
new file mode 100644
index 0000000..0d0e0df
--- /dev/null
+++ b/doc/distributions/dist_tutorial.qbk
@@ -0,0 +1,459 @@
+[/ def names all end in distrib to avoid clashes with names of functions]
+
+[def __binomial_distrib [link math_toolkit.dist_ref.dists.binomial_dist Binomial Distribution]]
+[def __chi_squared_distrib [link math_toolkit.dist_ref.dists.chi_squared_dist Chi Squared Distribution]]
+[def __normal_distrib [link math_toolkit.dist_ref.dists.normal_dist Normal Distribution]]
+[def __F_distrib [link math_toolkit.dist_ref.dists.f_dist Fisher F Distribution]]
+[def __students_t_distrib [link math_toolkit.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 of Distributions]
+
+[section:headers 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/my_distribution.hpp> or
+the "include all the distributions" header: <boost/math/distributions.hpp>.
+
+For example, to use the Students-t distribution include either
+<boost/math/students_t.hpp> or
+<boost/math/distributions.hpp>
+
+You also need to bring distribution names into scope,
+perhaps with a `using namespace boost::math;` declaration,
+
+or specific `using` declarations like `using boost::math::normal;` (*recommended*).
+
+[caution Some math function names are also used in namespace std so including <random> could cause ambiguity!]
+
+[endsect] [/ section:headers Headers and Namespaces]
+
+[section:objects Distributions are Objects]
+
+Each kind of distribution in this library is a class type - an object.
+
+[link 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.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; // Avoid potential ambiguity with names in std <random>
+ // Safer to declare specific functions with using statement(s):
+
+ using boost::math::beta_distribution;
+ using boost::math::binomial_distribution;
+ using boost::math::students_t;
+
+ // 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.
+
+[endsect] [/section:objects Distributions are Objects]
+
+
+[section:generic 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 any 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]
+
+The concept of a __random_variable is closely linked to the term __random_variate:
+a random variate is a particular value (outcome) of a random variable.
+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 vertical bar)
+/after/ the __random_variable (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
+['f(k| n, p)] = Pr(K = k|n, p) = probability of observing k successes out of n trials.
+K is the __random_variable, k is the __random_variate,
+the parameters are n (trials) and p (probability).
+] [/tip Random Variates and Distribution Parameters]
+
+[note By convention, __random_variate are lower case, usually k is integral, x if real, and
+__random_variable are upper case, K if integral, X if real. But this implementation treats
+all as floating point values `RealType`, so if you really want an integral result,
+you must round: see note on Discrete Probability Distributions below for details.]
+
+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.sf_implementation.handling_of_floating_point_infin
+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
+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.pol_overview Policies]. It is strongly
+recommended that you read the tutorial
+[link math_toolkit.pol_tutorial.understand_dis_quant
+Understanding Quantiles of Discrete Distributions] before
+using the quantile function on a discrete distribtion. The
+[link math_toolkit.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.
+]
+
+[endsect] [/ section:generic Generic operations common to all distributions are non-member functions]
+
+[section:complements Complements are supported too - and when to use them]
+
+Often you don't want the value of the CDF, but its complement, which is
+to say `1-p` rather than `p`. It is tempting to calculate the CDF and subtract
+it from `1`, but if `p` is very close to `1` then cancellation error
+will cause you to lose accuracy, perhaps totally.
+
+[link why_complements See below ['"Why and when to use 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, or percentiles or fractiles,
+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.
+
+With all distributions, even for more reasonable probability
+(unless the value of p can be represented exactly in the floating-point type)
+the loss of accuracy quickly becomes significant if you simply calculate probability from 1 - p
+(because it will be mostly garbage digits for p ~ 1).
+
+So always avoid, for example, using a probability near to unity like 0.99999
+
+`quantile(my_distribution, 0.99999)`
+
+and instead use
+
+`quantile(complement(my_distribution, 0.00001))`
+
+since 1 - 0.99999 is not exactly equal to 0.00001 when using floating-point arithmetic.
+
+This assumes that the 0.00001 value is either a constant,
+or can be computed by some manner other than subtracting 0.99999 from 1.
+
+] [/ tip *Why bother with complements anyway?]
+
+[endsect] [/ section:complements Complements are supported too - and why]
+
+[section:parameters 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.
+
+[endsect] [/ section:parameters Parameters can be calculated]
+
+[section:summary 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:summary Summary]
+[endsect] [/section:overview Overview]
+
+[section:weg Worked Examples]
+[include distribution_construction.qbk]
+[include students_t_examples.qbk]
+[include chi_squared_examples.qbk]
+[include f_dist_example.qbk]
+[include binomial_example.qbk]
+[include geometric_example.qbk]
+[include negative_binomial_example.qbk]
+[include normal_example.qbk]
+[/include inverse_gamma_example.qbk]
+[/include inverse_gaussian_example.qbk]
+[include inverse_chi_squared_eg.qbk]
+[include nc_chi_squared_example.qbk]
+[include error_handling_example.qbk]
+[include find_location_and_scale.qbk]
+[include nag_library.qbk]
+[include c_sharp.qbk]
+[endsect] [/section:weg Worked Examples]
+
+[include background.qbk]
+
+[endsect] [/ section:stat_tut Statistical Distributions Tutorial]
+
+[/ dist_tutorial.qbk
+ Copyright 2006, 2010, 2011 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).
+]
+
diff --git a/doc/distributions/distribution_construction.qbk b/doc/distributions/distribution_construction.qbk
new file mode 100644
index 0000000..169af6b
--- /dev/null
+++ b/doc/distributions/distribution_construction.qbk
@@ -0,0 +1,17 @@
+[section:dist_construct_eg Distribution Construction Examples]
+
+[import ../../example/distribution_construction.cpp]
+[distribution_construction_1]
+[distribution_construction_2]
+
+See [@../../example/distribution_construction.cpp distribution_construction.cpp] for full source code.
+
+[endsect] [/section:dist_construct_eg Distribution Construction Examples]
+
+[/
+ Copyright 2006, 2012 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).
+]
+
diff --git a/doc/distributions/error_handling_example.qbk b/doc/distributions/error_handling_example.qbk
new file mode 100644
index 0000000..0a68607
--- /dev/null
+++ b/doc/distributions/error_handling_example.qbk
@@ -0,0 +1,35 @@
+[section:error_eg Error Handling Example]
+
+See [link math_toolkit.error_handling error handling documentation]
+for a detailed explanation of the mechanism of handling errors,
+including the common "bad" arguments to distributions and functions,
+and how to use __policy_section to control it.
+
+But, by default, *exceptions will be raised*, for domain errors,
+pole errors, numeric overflow, and internal evaluation errors.
+To avoid the exceptions from getting thrown and instead get
+an appropriate value returned, usually a NaN (domain errors
+pole errors or internal errors), or infinity (from overflow),
+you need to change the policy.
+
+[import ../../example/error_handling_example.cpp]
+
+[error_handling_example]
+
+[caution If throwing of exceptions is enabled (the default) but
+you do *not* have try & catch block,
+then the program will terminate with an uncaught exception and probably abort.
+
+Therefore to get the benefit of helpful error messages, enabling *all exceptions
+and using try & catch* is recommended for most applications.
+
+However, for simplicity, the is not done for most examples.]
+
+[endsect] [/section:error_eg Error Handling Example]
+[/
+ Copyright 2007 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).
+]
+
diff --git a/doc/distributions/exponential.qbk b/doc/distributions/exponential.qbk
new file mode 100644
index 0000000..af83a29
--- /dev/null
+++ b/doc/distributions/exponential.qbk
@@ -0,0 +1,108 @@
+[section:exp_dist Exponential Distribution]
+
+``#include <boost/math/distributions/exponential.hpp>``
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class exponential_distribution;
+
+ typedef exponential_distribution<> exponential;
+
+ template <class RealType, class ``__Policy``>
+ class exponential_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ exponential_distribution(RealType lambda = 1);
+
+ RealType lambda()const;
+ };
+
+
+The [@http://en.wikipedia.org/wiki/Exponential_distribution exponential distribution]
+is a [@http://en.wikipedia.org/wiki/Probability_distribution continuous probability distribution]
+with PDF:
+
+[equation exponential_dist_ref1]
+
+It is often used to model the time between independent
+events that happen at a constant average rate.
+
+The following graph shows how the distribution changes for different
+values of the rate parameter lambda:
+
+[graph exponential_pdf]
+
+[h4 Member Functions]
+
+ exponential_distribution(RealType lambda = 1);
+
+Constructs an
+[@http://en.wikipedia.org/wiki/Exponential_distribution Exponential distribution]
+with parameter /lambda/.
+Lambda is defined as the reciprocal of the scale parameter.
+
+Requires lambda > 0, otherwise calls __domain_error.
+
+ RealType lambda()const;
+
+Accessor function returns the lambda parameter of the distribution.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
+that are generic to all distributions are supported: __usual_accessors.
+
+The domain of the random variable is \[0, +[infin]\].
+
+[h4 Accuracy]
+
+The exponential distribution is implemented in terms of the
+standard library functions `exp`, `log`, `log1p` and `expm1`
+and as such should have very low error rates.
+
+[h4 Implementation]
+
+In the following table [lambda] is the parameter lambda of the distribution,
+/x/ is the random variate, /p/ is the probability and /q = 1-p/.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Using the relation: pdf = [lambda] * exp(-[lambda] * x) ]]
+[[cdf][Using the relation: p = 1 - exp(-x * [lambda]) = -expm1(-x * [lambda]) ]]
+[[cdf complement][Using the relation: q = exp(-x * [lambda]) ]]
+[[quantile][Using the relation: x = -log(1-p) / [lambda] = -log1p(-p) / [lambda]]]
+[[quantile from the complement][Using the relation: x = -log(q) / [lambda]]]
+[[mean][1/[lambda]]]
+[[standard deviation][1/[lambda]]]
+[[mode][0]]
+[[skewness][2]]
+[[kurtosis][9]]
+[[kurtosis excess][6]]
+]
+
+[h4 references]
+
+* [@http://mathworld.wolfram.com/ExponentialDistribution.html Weisstein, Eric W. "Exponential Distribution." From MathWorld--A Wolfram Web Resource]
+* [@http://documents.wolfram.com/calccenter/Functions/ListsMatrices/Statistics/ExponentialDistribution.html Wolfram Mathematica calculator]
+* [@http://www.itl.nist.gov/div898/handbook/eda/section3/eda3667.htm NIST Exploratory Data Analysis]
+* [@http://en.wikipedia.org/wiki/Exponential_distribution Wikipedia Exponential distribution]
+
+(See also the reference documentation for the related __extreme_distrib.)
+
+*
+[@http://www.worldscibooks.com/mathematics/p191.html Extreme Value Distributions, Theory and Applications
+Samuel Kotz & Saralees Nadarajah]
+discuss the relationship of the types of extreme value distributions.
+
+[endsect][/section:exp_dist Exponential]
+
+[/ exponential.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).
+]
+
diff --git a/doc/distributions/extreme_value.qbk b/doc/distributions/extreme_value.qbk
new file mode 100644
index 0000000..affc509
--- /dev/null
+++ b/doc/distributions/extreme_value.qbk
@@ -0,0 +1,119 @@
+[section:extreme_dist Extreme Value Distribution]
+
+``#include <boost/math/distributions/extreme.hpp>``
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class extreme_value_distribution;
+
+ typedef extreme_value_distribution<> extreme_value;
+
+ template <class RealType, class ``__Policy``>
+ class extreme_value_distribution
+ {
+ public:
+ typedef RealType value_type;
+
+ extreme_value_distribution(RealType location = 0, RealType scale = 1);
+
+ RealType scale()const;
+ RealType location()const;
+ };
+
+There are various
+[@http://mathworld.wolfram.com/ExtremeValueDistribution.html extreme value distributions]
+: this implementation represents the maximum case,
+and is variously known as a Fisher-Tippett distribution,
+a log-Weibull distribution or a Gumbel distribution.
+
+Extreme value theory is important for assessing risk for highly unusual events,
+such as 100-year floods.
+
+More information can be found on the
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda366g.htm NIST],
+[@http://en.wikipedia.org/wiki/Extreme_value_distribution Wikipedia],
+[@http://mathworld.wolfram.com/ExtremeValueDistribution.html Mathworld],
+and [@http://en.wikipedia.org/wiki/Extreme_value_theory Extreme value theory]
+websites.
+
+The relationship of the types of extreme value distributions, of which this is but one, is
+discussed by
+[@http://www.worldscibooks.com/mathematics/p191.html Extreme Value Distributions, Theory and Applications
+Samuel Kotz & Saralees Nadarajah].
+
+The distribution has a PDF given by:
+
+f(x) = (1/scale) e[super -(x-location)/scale] e[super -e[super -(x-location)/scale]]
+
+Which in the standard case (scale = 1, location = 0) reduces to:
+
+f(x) = e[super -x]e[super -e[super -x]]
+
+The following graph illustrates how the PDF varies with the location parameter:
+
+[graph extreme_value_pdf1]
+
+And this graph illustrates how the PDF varies with the shape parameter:
+
+[graph extreme_value_pdf2]
+
+[h4 Member Functions]
+
+ extreme_value_distribution(RealType location = 0, RealType scale = 1);
+
+Constructs an Extreme Value distribution with the specified location and scale
+parameters.
+
+Requires `scale > 0`, otherwise calls __domain_error.
+
+ RealType location()const;
+
+Returns the location parameter of the distribution.
+
+ RealType scale()const;
+
+Returns the scale parameter of the distribution.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
+that are generic to all distributions are supported: __usual_accessors.
+
+The domain of the random parameter is \[-[infin], +[infin]\].
+
+[h4 Accuracy]
+
+The extreme value distribution is implemented in terms of the
+standard library `exp` and `log` functions and as such should have very low
+error rates.
+
+[h4 Implementation]
+
+In the following table:
+/a/ is the location parameter, /b/ is the scale parameter,
+/x/ is the random variate, /p/ is the probability and /q = 1-p/.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Using the relation: pdf = exp((a-x)/b) * exp(-exp((a-x)/b)) / b ]]
+[[cdf][Using the relation: p = exp(-exp((a-x)/b)) ]]
+[[cdf complement][Using the relation: q = -expm1(-exp((a-x)/b)) ]]
+[[quantile][Using the relation: a - log(-log(p)) * b]]
+[[quantile from the complement][Using the relation: a - log(-log1p(-q)) * b]]
+[[mean][a + [@http://en.wikipedia.org/wiki/Euler-Mascheroni_constant Euler-Mascheroni-constant] * b]]
+[[standard deviation][pi * b / sqrt(6)]]
+[[mode][The same as the location parameter /a/.]]
+[[skewness][12 * sqrt(6) * zeta(3) / pi[super 3] ]]
+[[kurtosis][27 / 5]]
+[[kurtosis excess][kurtosis - 3 or 12 / 5]]
+]
+
+[endsect][/section:extreme_dist Extreme Value]
+
+[/ extreme_value.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).
+]
+
diff --git a/doc/distributions/f_dist_example.qbk b/doc/distributions/f_dist_example.qbk
new file mode 100644
index 0000000..1601199
--- /dev/null
+++ b/doc/distributions/f_dist_example.qbk
@@ -0,0 +1,220 @@
+[section:f_eg F Distribution Examples]
+
+Imagine that you want to compare the standard deviations of two
+sample to determine if they differ in any significant way, in this
+situation you use the F distribution and perform an F-test. This
+situation commonly occurs when conducting a process change comparison:
+"is a new process more consistent that the old one?".
+
+In this example we'll be using the data for ceramic strength from
+[@http://www.itl.nist.gov/div898/handbook/eda/section4/eda42a1.htm
+http://www.itl.nist.gov/div898/handbook/eda/section4/eda42a1.htm].
+The data for this case study were collected by Said Jahanmir of the
+NIST Ceramics Division in 1996 in connection with a NIST/industry
+ceramics consortium for strength optimization of ceramic strength.
+
+The example program is [@../../example/f_test.cpp f_test.cpp],
+program output has been deliberately made as similar as possible
+to the DATAPLOT output in the corresponding
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda359.htm
+NIST EngineeringStatistics Handbook example].
+
+We'll begin by defining the procedure to conduct the test:
+
+ void f_test(
+ double sd1, // Sample 1 std deviation
+ double sd2, // Sample 2 std deviation
+ double N1, // Sample 1 size
+ double N2, // Sample 2 size
+ double alpha) // Significance level
+ {
+
+The procedure begins by printing out a summary of our input data:
+
+ using namespace std;
+ using namespace boost::math;
+
+ // Print header:
+ cout <<
+ "____________________________________\n"
+ "F test for equal standard deviations\n"
+ "____________________________________\n\n";
+ cout << setprecision(5);
+ cout << "Sample 1:\n";
+ cout << setw(55) << left << "Number of Observations" << "= " << N1 << "\n";
+ cout << setw(55) << left << "Sample Standard Deviation" << "= " << sd1 << "\n\n";
+ cout << "Sample 2:\n";
+ cout << setw(55) << left << "Number of Observations" << "= " << N2 << "\n";
+ cout << setw(55) << left << "Sample Standard Deviation" << "= " << sd2 << "\n\n";
+
+The test statistic for an F-test is simply the ratio of the square of
+the two standard deviations:
+
+F = s[sub 1][super 2] / s[sub 2][super 2]
+
+where s[sub 1] is the standard deviation of the first sample and s[sub 2]
+is the standard deviation of the second sample. Or in code:
+
+ double F = (sd1 / sd2);
+ F *= F;
+ cout << setw(55) << left << "Test Statistic" << "= " << F << "\n\n";
+
+At this point a word of caution: the F distribution is asymmetric,
+so we have to be careful how we compute the tests, the following table
+summarises the options available:
+
+[table
+[[Hypothesis][Test]]
+[[The null-hypothesis: there is no difference in standard deviations (two sided test)]
+ [Reject if F <= F[sub (1-alpha/2; N1-1, N2-1)] or F >= F[sub (alpha/2; N1-1, N2-1)] ]]
+[[The alternative hypothesis: there is a difference in means (two sided test)]
+ [Reject if F[sub (1-alpha/2; N1-1, N2-1)] <= F <= F[sub (alpha/2; N1-1, N2-1)] ]]
+[[The alternative hypothesis: Standard deviation of sample 1 is greater
+than that of sample 2]
+ [Reject if F < F[sub (alpha; N1-1, N2-1)] ]]
+[[The alternative hypothesis: Standard deviation of sample 1 is less
+than that of sample 2]
+ [Reject if F > F[sub (1-alpha; N1-1, N2-1)] ]]
+]
+
+Where F[sub (1-alpha; N1-1, N2-1)] is the lower critical value of the F distribution
+with degrees of freedom N1-1 and N2-1, and F[sub (alpha; N1-1, N2-1)] is the upper
+critical value of the F distribution with degrees of freedom N1-1 and N2-1.
+
+The upper and lower critical values can be computed using the quantile function:
+
+F[sub (1-alpha; N1-1, N2-1)] = `quantile(fisher_f(N1-1, N2-1), alpha)`
+
+F[sub (alpha; N1-1, N2-1)] = `quantile(complement(fisher_f(N1-1, N2-1), alpha))`
+
+In our example program we need both upper and lower critical values for alpha
+and for alpha/2:
+
+ double ucv = quantile(complement(dist, alpha));
+ double ucv2 = quantile(complement(dist, alpha / 2));
+ double lcv = quantile(dist, alpha);
+ double lcv2 = quantile(dist, alpha / 2);
+ cout << setw(55) << left << "Upper Critical Value at alpha: " << "= "
+ << setprecision(3) << scientific << ucv << "\n";
+ cout << setw(55) << left << "Upper Critical Value at alpha/2: " << "= "
+ << setprecision(3) << scientific << ucv2 << "\n";
+ cout << setw(55) << left << "Lower Critical Value at alpha: " << "= "
+ << setprecision(3) << scientific << lcv << "\n";
+ cout << setw(55) << left << "Lower Critical Value at alpha/2: " << "= "
+ << setprecision(3) << scientific << lcv2 << "\n\n";
+
+The final step is to perform the comparisons given above, and print
+out whether the hypothesis is rejected or not:
+
+ cout << setw(55) << left <<
+ "Results for Alternative Hypothesis and alpha" << "= "
+ << setprecision(4) << fixed << alpha << "\n\n";
+ cout << "Alternative Hypothesis Conclusion\n";
+
+ cout << "Standard deviations are unequal (two sided test) ";
+ if((ucv2 < F) || (lcv2 > F))
+ cout << "ACCEPTED\n";
+ else
+ cout << "REJECTED\n";
+
+ cout << "Standard deviation 1 is less than standard deviation 2 ";
+ if(lcv > F)
+ cout << "ACCEPTED\n";
+ else
+ cout << "REJECTED\n";
+
+ cout << "Standard deviation 1 is greater than standard deviation 2 ";
+ if(ucv < F)
+ cout << "ACCEPTED\n";
+ else
+ cout << "REJECTED\n";
+ cout << endl << endl;
+
+Using the ceramic strength data as an example we get the following
+output:
+
+[pre
+'''F test for equal standard deviations
+____________________________________
+
+Sample 1:
+Number of Observations = 240
+Sample Standard Deviation = 65.549
+
+Sample 2:
+Number of Observations = 240
+Sample Standard Deviation = 61.854
+
+Test Statistic = 1.123
+
+CDF of test statistic: = 8.148e-001
+Upper Critical Value at alpha: = 1.238e+000
+Upper Critical Value at alpha/2: = 1.289e+000
+Lower Critical Value at alpha: = 8.080e-001
+Lower Critical Value at alpha/2: = 7.756e-001
+
+Results for Alternative Hypothesis and alpha = 0.0500
+
+Alternative Hypothesis Conclusion
+Standard deviations are unequal (two sided test) REJECTED
+Standard deviation 1 is less than standard deviation 2 REJECTED
+Standard deviation 1 is greater than standard deviation 2 REJECTED'''
+]
+
+In this case we are unable to reject the null-hypothesis, and must instead
+reject the alternative hypothesis.
+
+By contrast let's see what happens when we use some different
+[@http://www.itl.nist.gov/div898/handbook/prc/section3/prc32.htm
+sample data]:, once again from the NIST Engineering Statistics Handbook:
+A new procedure to assemble a device is introduced and tested for
+possible improvement in time of assembly. The question being addressed
+is whether the standard deviation of the new assembly process (sample 2) is
+better (i.e., smaller) than the standard deviation for the old assembly
+process (sample 1).
+
+[pre
+'''____________________________________
+F test for equal standard deviations
+____________________________________
+
+Sample 1:
+Number of Observations = 11.00000
+Sample Standard Deviation = 4.90820
+
+Sample 2:
+Number of Observations = 9.00000
+Sample Standard Deviation = 2.58740
+
+Test Statistic = 3.59847
+
+CDF of test statistic: = 9.589e-001
+Upper Critical Value at alpha: = 3.347e+000
+Upper Critical Value at alpha/2: = 4.295e+000
+Lower Critical Value at alpha: = 3.256e-001
+Lower Critical Value at alpha/2: = 2.594e-001
+
+Results for Alternative Hypothesis and alpha = 0.0500
+
+Alternative Hypothesis Conclusion
+Standard deviations are unequal (two sided test) REJECTED
+Standard deviation 1 is less than standard deviation 2 REJECTED
+Standard deviation 1 is greater than standard deviation 2 ACCEPTED'''
+]
+
+In this case we take our null hypothesis as "standard deviation 1 is
+less than or equal to standard deviation 2", since this represents the "no change"
+situation. So we want to compare the upper critical value at /alpha/
+(a one sided test) with the test statistic, and since 3.35 < 3.6 this
+hypothesis must be rejected. We therefore conclude that there is a change
+for the better in our standard deviation.
+
+[endsect][/section:f_eg F Distribution]
+
+[/
+ 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).
+]
+
diff --git a/doc/distributions/find_location_and_scale.qbk b/doc/distributions/find_location_and_scale.qbk
new file mode 100644
index 0000000..b722aec
--- /dev/null
+++ b/doc/distributions/find_location_and_scale.qbk
@@ -0,0 +1,39 @@
+[section:find_eg Find Location and Scale Examples]
+
+[section:find_location_eg Find Location (Mean) Example]
+[import ../../example/find_location_example.cpp]
+[find_location1]
+[find_location2]
+See [@../../example/find_location_example.cpp find_location_example.cpp]
+for full source code: the program output looks like this:
+[find_location_example_output]
+[endsect] [/section:find_location_eg Find Location (Mean) Example]
+
+[section:find_scale_eg Find Scale (Standard Deviation) Example]
+[import ../../example/find_scale_example.cpp]
+[find_scale1]
+[find_scale2]
+See [@../../example/find_scale_example.cpp find_scale_example.cpp]
+for full source code: the program output looks like this:
+[find_scale_example_output]
+[endsect] [/section:find_scale_eg Scale (Standard Deviation) Example]
+[section:find_mean_and_sd_eg Find mean and standard deviation example]
+
+[import ../../example/find_mean_and_sd_normal.cpp]
+[normal_std]
+[normal_find_location_and_scale_eg]
+See [@../../example/find_mean_and_sd_normal.cpp find_mean_and_sd_normal.cpp]
+for full source code & appended program output.
+[endsect] [/find_mean_and_sd_eg Find mean and standard deviation example]
+
+[endsect] [/section:find_eg Find Location and Scale Examples]
+
+
+
+[/
+ 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).
+]
+
diff --git a/doc/distributions/fisher.qbk b/doc/distributions/fisher.qbk
new file mode 100644
index 0000000..f09388d
--- /dev/null
+++ b/doc/distributions/fisher.qbk
@@ -0,0 +1,190 @@
+[section:f_dist F Distribution]
+
+``#include <boost/math/distributions/fisher_f.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class fisher_f_distribution;
+
+ typedef fisher_f_distribution<> fisher_f;
+
+ template <class RealType, class ``__Policy``>
+ class fisher_f_distribution
+ {
+ public:
+ typedef RealType value_type;
+
+ // Construct:
+ fisher_f_distribution(const RealType& i, const RealType& j);
+
+ // Accessors:
+ RealType degrees_of_freedom1()const;
+ RealType degrees_of_freedom2()const;
+ };
+
+ }} //namespaces
+
+The F distribution is a continuous distribution that arises when testing
+whether two samples have the same variance. If [chi][super 2][sub m][space] and
+[chi][super 2][sub n][space] are independent variates each distributed as
+Chi-Squared with /m/ and /n/ degrees of freedom, then the test statistic:
+
+F[sub n,m][space] = ([chi][super 2][sub n][space] / n) / ([chi][super 2][sub m][space] / m)
+
+Is distributed over the range \[0, [infin]\] with an F distribution, and
+has the PDF:
+
+[equation fisher_pdf]
+
+The following graph illustrates how the PDF varies depending on the
+two degrees of freedom parameters.
+
+[graph fisher_f_pdf]
+
+
+[h4 Member Functions]
+
+ fisher_f_distribution(const RealType& df1, const RealType& df2);
+
+Constructs an F-distribution with numerator degrees of freedom /df1/
+and denominator degrees of freedom /df2/.
+
+Requires that /df1/ and /df2/ are both greater than zero, otherwise __domain_error
+is called.
+
+ RealType degrees_of_freedom1()const;
+
+Returns the numerator degrees of freedom parameter of the distribution.
+
+ RealType degrees_of_freedom2()const;
+
+Returns the denominator degrees of freedom parameter of the distribution.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
+that are generic to all distributions are supported: __usual_accessors.
+
+The domain of the random variable is \[0, +[infin]\].
+
+[h4 Examples]
+
+Various [link math_toolkit.stat_tut.weg.f_eg worked examples] are
+available illustrating the use of the F Distribution.
+
+[h4 Accuracy]
+
+The normal distribution is implemented in terms of the
+[link math_toolkit.sf_beta.ibeta_function incomplete beta function]
+and its [link math_toolkit.sf_beta.ibeta_inv_function inverses],
+refer to those functions for accuracy data.
+
+[h4 Implementation]
+
+In the following table /v1/ and /v2/ are the first and second
+degrees of freedom parameters of the distribution,
+/x/ is the random variate, /p/ is the probability, and /q = 1-p/.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][The usual form of the PDF is given by:
+
+[equation fisher_pdf]
+
+However, that form is hard to evaluate directly without incurring problems with
+either accuracy or numeric overflow.
+
+Direct differentiation of the CDF expressed in terms of the incomplete beta function
+
+led to the following two formulas:
+
+f[sub v1,v2](x) = y * __ibeta_derivative(v2 \/ 2, v1 \/ 2, v2 \/ (v2 + v1 * x))
+
+with y = (v2 * v1) \/ ((v2 + v1 * x) * (v2 + v1 * x))
+
+and
+
+f[sub v1,v2](x) = y * __ibeta_derivative(v1 \/ 2, v2 \/ 2, v1 * x \/ (v2 + v1 * x))
+
+with y = (z * v1 - x * v1 * v1) \/ z[super 2]
+
+and z = v2 + v1 * x
+
+The first of these is used for v1 * x > v2, otherwise the second is used.
+
+The aim is to keep the /x/ argument to __ibeta_derivative away from 1 to avoid
+rounding error. ]]
+[[cdf][Using the relations:
+
+p = __ibeta(v1 \/ 2, v2 \/ 2, v1 * x \/ (v2 + v1 * x))
+
+and
+
+p = __ibetac(v2 \/ 2, v1 \/ 2, v2 \/ (v2 + v1 * x))
+
+The first is used for v1 * x > v2, otherwise the second is used.
+
+The aim is to keep the /x/ argument to __ibeta well away from 1 to
+avoid rounding error. ]]
+
+[[cdf complement][Using the relations:
+
+p = __ibetac(v1 \/ 2, v2 \/ 2, v1 * x \/ (v2 + v1 * x))
+
+and
+
+p = __ibeta(v2 \/ 2, v1 \/ 2, v2 \/ (v2 + v1 * x))
+
+The first is used for v1 * x < v2, otherwise the second is used.
+
+The aim is to keep the /x/ argument to __ibeta well away from 1 to
+avoid rounding error. ]]
+[[quantile][Using the relation:
+
+x = v2 * a \/ (v1 * b)
+
+where:
+
+a = __ibeta_inv(v1 \/ 2, v2 \/ 2, p)
+
+and
+
+b = 1 - a
+
+Quantities /a/ and /b/ are both computed by __ibeta_inv without the
+subtraction implied above.]]
+[[quantile
+
+from the complement][Using the relation:
+
+x = v2 * a \/ (v1 * b)
+
+where
+
+a = __ibetac_inv(v1 \/ 2, v2 \/ 2, p)
+
+and
+
+b = 1 - a
+
+Quantities /a/ and /b/ are both computed by __ibetac_inv without the
+subtraction implied above.]]
+[[mean][v2 \/ (v2 - 2)]]
+[[variance][2 * v2[super 2 ] * (v1 + v2 - 2) \/ (v1 * (v2 - 2) * (v2 - 2) * (v2 - 4))]]
+[[mode][v2 * (v1 - 2) \/ (v1 * (v2 + 2))]]
+[[skewness][2 * (v2 + 2 * v1 - 2) * sqrt((2 * v2 - 8) \/ (v1 * (v2 + v1 - 2))) \/ (v2 - 6)]]
+[[kurtosis and kurtosis excess]
+ [Refer to, [@http://mathworld.wolfram.com/F-Distribution.html
+ Weisstein, Eric W. "F-Distribution." From MathWorld--A Wolfram Web Resource.] ]]
+]
+
+[endsect][/section:f_dist F distribution]
+
+[/ fisher.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).
+]
diff --git a/doc/distributions/gamma.qbk b/doc/distributions/gamma.qbk
new file mode 100644
index 0000000..9d5faab
--- /dev/null
+++ b/doc/distributions/gamma.qbk
@@ -0,0 +1,139 @@
+[section:gamma_dist Gamma (and Erlang) Distribution]
+
+``#include <boost/math/distributions/gamma.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class gamma_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ gamma_distribution(RealType shape, RealType scale = 1)
+
+ RealType shape()const;
+ RealType scale()const;
+ };
+
+ }} // namespaces
+
+The gamma distribution is a continuous probability distribution.
+When the shape parameter is an integer then it is known as the
+Erlang Distribution. It is also closely related to the Poisson
+and Chi Squared Distributions.
+
+When the shape parameter has an integer value, the distribution is the
+[@http://en.wikipedia.org/wiki/Erlang_distribution Erlang distribution].
+Since this can be produced by ensuring that the shape parameter has an
+integer value > 0, the Erlang distribution is not separately implemented.
+
+[note
+To avoid potential confusion with the gamma functions, this
+distribution does not provide the typedef:
+
+``typedef gamma_distribution<double> gamma;``
+
+Instead if you want a double precision gamma distribution you can write
+
+``boost::math::gamma_distribution<> my_gamma(1, 1);``
+]
+
+For shape parameter /k/ and scale parameter [theta][space] it is defined by the
+probability density function:
+
+[equation gamma_dist_ref1]
+
+Sometimes an alternative formulation is used: given parameters
+[alpha][space]= k and [beta][space]= 1 / [theta], then the
+distribution can be defined by the PDF:
+
+[equation gamma_dist_ref2]
+
+In this form the inverse scale parameter is called a /rate parameter/.
+
+Both forms are in common usage: this library uses the first definition
+throughout. Therefore to construct a Gamma Distribution from a ['rate
+parameter], you should pass the reciprocal of the rate as the scale parameter.
+
+The following two graphs illustrate how the PDF of the gamma distribution
+varies as the parameters vary:
+
+[graph gamma1_pdf]
+
+[graph gamma2_pdf]
+
+The [*Erlang Distribution] is the same as the Gamma, but with the shape parameter
+an integer. It is often expressed using a /rate/ rather than a /scale/ as the
+second parameter (remember that the rate is the reciprocal of the scale).
+
+Internally the functions used to implement the Gamma Distribution are
+already optimised for small-integer arguments, so in general there should
+be no great loss of performance from using a Gamma Distribution rather than
+a dedicated Erlang Distribution.
+
+[h4 Member Functions]
+
+ gamma_distribution(RealType shape, RealType scale = 1);
+
+Constructs a gamma distribution with shape /shape/ and
+scale /scale/.
+
+Requires that the shape and scale parameters are greater than zero, otherwise calls
+__domain_error.
+
+ RealType shape()const;
+
+Returns the /shape/ parameter of this distribution.
+
+ RealType scale()const;
+
+Returns the /scale/ parameter of this distribution.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] that are generic to all
+distributions are supported: __usual_accessors.
+
+The domain of the random variable is \[0,+[infin]\].
+
+[h4 Accuracy]
+
+The gamma distribution is implemented in terms of the
+incomplete gamma functions __gamma_p and __gamma_q and their
+inverses __gamma_p_inv and __gamma_q_inv: refer to the accuracy
+data for those functions for more information.
+
+[h4 Implementation]
+
+In the following table /k/ is the shape parameter of the distribution,
+[theta][space] is its scale parameter, /x/ is the random variate, /p/ is the probability
+and /q = 1-p/.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Using the relation: pdf = __gamma_p_derivative(k, x / [theta]) / [theta] ]]
+[[cdf][Using the relation: p = __gamma_p(k, x / [theta]) ]]
+[[cdf complement][Using the relation: q = __gamma_q(k, x / [theta]) ]]
+[[quantile][Using the relation: x = [theta][space]* __gamma_p_inv(k, p) ]]
+[[quantile from the complement][Using the relation: x = [theta][space]* __gamma_q_inv(k, p) ]]
+[[mean][k[theta] ]]
+[[variance][k[theta][super 2] ]]
+[[mode][(k-1)[theta][space] for ['k>1] otherwise a __domain_error ]]
+[[skewness][2 / sqrt(k) ]]
+[[kurtosis][3 + 6 / k]]
+[[kurtosis excess][6 / k ]]
+]
+
+[endsect][/section:gamma_dist Gamma (and Erlang) Distribution]
+
+
+[/
+ Copyright 2006, 2010 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).
+]
+
diff --git a/doc/distributions/geometric.qbk b/doc/distributions/geometric.qbk
new file mode 100644
index 0000000..5129b45
--- /dev/null
+++ b/doc/distributions/geometric.qbk
@@ -0,0 +1,350 @@
+[section:geometric_dist Geometric Distribution]
+
+``#include <boost/math/distributions/geometric.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class geometric_distribution;
+
+ typedef geometric_distribution<> geometric;
+
+ template <class RealType, class ``__Policy``>
+ class geometric_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+ // Constructor from success_fraction:
+ geometric_distribution(RealType p);
+
+ // Parameter accessors:
+ RealType success_fraction() const;
+ RealType successes() const;
+
+ // Bounds on success fraction:
+ static RealType find_lower_bound_on_p(
+ RealType trials,
+ RealType successes,
+ RealType probability); // alpha
+ static RealType find_upper_bound_on_p(
+ RealType trials,
+ RealType successes,
+ RealType probability); // alpha
+
+ // Estimate min/max number of trials:
+ static RealType find_minimum_number_of_trials(
+ RealType k, // Number of failures.
+ RealType p, // Success fraction.
+ RealType probability); // Probability threshold alpha.
+ static RealType find_maximum_number_of_trials(
+ RealType k, // Number of failures.
+ RealType p, // Success fraction.
+ RealType probability); // Probability threshold alpha.
+ };
+
+ }} // namespaces
+
+The class type `geometric_distribution` represents a
+[@http://en.wikipedia.org/wiki/geometric_distribution geometric distribution]:
+it is used when there are exactly two mutually exclusive outcomes of a
+[@http://en.wikipedia.org/wiki/Bernoulli_trial Bernoulli trial]:
+these outcomes are labelled "success" and "failure".
+
+For [@http://en.wikipedia.org/wiki/Bernoulli_trial Bernoulli trials]
+each with success fraction /p/, the geometric distribution gives
+the probability of observing /k/ trials (failures, events, occurrences, or arrivals)
+before the first success.
+
+[note For this implementation, the set of trials *includes zero*
+(unlike another definition where the set of trials starts at one, sometimes named /shifted/).]
+The geometric distribution assumes that success_fraction /p/ is fixed for all /k/ trials.
+
+The probability that there are /k/ failures before the first success is
+
+__spaces Pr(Y=/k/) = (1-/p/)[super /k/]/p/
+
+For example, when throwing a 6-face dice the success probability /p/ = 1/6 = 0.1666[recur][space].
+Throwing repeatedly until a /three/ appears,
+the probability distribution of the number of times /not-a-three/ is thrown
+is geometric.
+
+Geometric distribution has the Probability Density Function PDF:
+
+__spaces (1-/p/)[super /k/]/p/
+
+The following graph illustrates how the PDF and CDF vary for three examples
+of the success fraction /p/,
+(when considering the geometric distribution as a continuous function),
+
+[graph geometric_pdf_2]
+
+[graph geometric_cdf_2]
+
+and as discrete.
+
+[graph geometric_pdf_discrete]
+
+[graph geometric_cdf_discrete]
+
+
+[h4 Related Distributions]
+
+The geometric distribution is a special case of
+the __negative_binomial_distrib with successes parameter /r/ = 1,
+so only one first and only success is required : thus by definition
+__spaces `geometric(p) == negative_binomial(1, p)`
+
+ negative_binomial_distribution(RealType r, RealType success_fraction);
+ negative_binomial nb(1, success_fraction);
+ geometric g(success_fraction);
+ ASSERT(pdf(nb, 1) == pdf(g, 1));
+
+This implementation uses real numbers for the computation throughout
+(because it uses the *real-valued* power and exponential functions).
+So to obtain a conventional strictly-discrete geometric distribution
+you must ensure that an integer value is provided for the number of trials
+(random variable) /k/,
+and take integer values (floor or ceil functions) from functions that return
+a number of successes.
+
+[discrete_quantile_warning geometric]
+
+[h4 Member Functions]
+
+[h5 Constructor]
+
+ geometric_distribution(RealType p);
+
+Constructor: /p/ or success_fraction is the probability of success of a single trial.
+
+Requires: `0 <= p <= 1`.
+
+[h5 Accessors]
+
+ RealType success_fraction() const; // successes / trials (0 <= p <= 1)
+
+Returns the success_fraction parameter /p/ from which this distribution was constructed.
+
+ RealType successes() const; // required successes always one,
+ // included for compatibility with negative binomial distribution
+ // with successes r == 1.
+
+Returns unity.
+
+The following functions are equivalent to those provided for the negative binomial,
+with successes = 1, but are provided here for completeness.
+
+The best method of calculation for the following functions is disputed:
+see __binomial_distrib and __negative_binomial_distrib for more discussion.
+
+[h5 Lower Bound on success_fraction Parameter ['p]]
+
+ static RealType find_lower_bound_on_p(
+ RealType failures,
+ RealType probability) // (0 <= alpha <= 1), 0.05 equivalent to 95% confidence.
+
+Returns a *lower bound* on the success fraction:
+
+[variablelist
+[[failures][The total number of failures before the 1st success.]]
+[[alpha][The largest acceptable probability that the true value of
+ the success fraction is [*less than] the value returned.]]
+]
+
+For example, if you observe /k/ failures from /n/ trials
+the best estimate for the success fraction is simply 1/['n], but if you
+want to be 95% sure that the true value is [*greater than] some value,
+['p[sub min]], then:
+
+ p``[sub min]`` = geometric_distribution<RealType>::
+ find_lower_bound_on_p(failures, 0.05);
+
+[link math_toolkit.stat_tut.weg.neg_binom_eg.neg_binom_conf See negative_binomial confidence interval example.]
+
+This function uses the Clopper-Pearson method of computing the lower bound on the
+success fraction, whilst many texts refer to this method as giving an "exact"
+result in practice it produces an interval that guarantees ['at least] the
+coverage required, and may produce pessimistic estimates for some combinations
+of /failures/ and /successes/. See:
+
+[@http://www.ucs.louisiana.edu/~kxk4695/Discrete_new.pdf
+Yong Cai and K. Krishnamoorthy, A Simple Improved Inferential Method for Some Discrete Distributions.
+Computational statistics and data analysis, 2005, vol. 48, no3, 605-621].
+
+[h5 Upper Bound on success_fraction Parameter p]
+
+ static RealType find_upper_bound_on_p(
+ RealType trials,
+ RealType alpha); // (0 <= alpha <= 1), 0.05 equivalent to 95% confidence.
+
+Returns an *upper bound* on the success fraction:
+
+[variablelist
+[[trials][The total number of trials conducted.]]
+[[alpha][The largest acceptable probability that the true value of
+ the success fraction is [*greater than] the value returned.]]
+]
+
+For example, if you observe /k/ successes from /n/ trials the
+best estimate for the success fraction is simply ['k/n], but if you
+want to be 95% sure that the true value is [*less than] some value,
+['p[sub max]], then:
+
+ p``[sub max]`` = geometric_distribution<RealType>::find_upper_bound_on_p(
+ k, 0.05);
+
+[link math_toolkit.stat_tut.weg.neg_binom_eg.neg_binom_conf See negative binomial confidence interval example.]
+
+This function uses the Clopper-Pearson method of computing the lower bound on the
+success fraction, whilst many texts refer to this method as giving an "exact"
+result in practice it produces an interval that guarantees ['at least] the
+coverage required, and may produce pessimistic estimates for some combinations
+of /failures/ and /successes/. See:
+
+[@http://www.ucs.louisiana.edu/~kxk4695/Discrete_new.pdf
+Yong Cai and K. Krishnamoorthy, A Simple Improved Inferential Method for Some Discrete Distributions.
+Computational statistics and data analysis, 2005, vol. 48, no3, 605-621].
+
+[h5 Estimating Number of Trials to Ensure at Least a Certain Number of Failures]
+
+ static RealType find_minimum_number_of_trials(
+ RealType k, // number of failures.
+ RealType p, // success fraction.
+ RealType alpha); // probability threshold (0.05 equivalent to 95%).
+
+This functions estimates the number of trials required to achieve a certain
+probability that [*more than ['k] failures will be observed].
+
+[variablelist
+[[k][The target number of failures to be observed.]]
+[[p][The probability of ['success] for each trial.]]
+[[alpha][The maximum acceptable ['risk] that only ['k] failures or fewer will be observed.]]
+]
+
+For example:
+
+ geometric_distribution<RealType>::find_minimum_number_of_trials(10, 0.5, 0.05);
+
+Returns the smallest number of trials we must conduct to be 95% (1-0.05) sure
+of seeing 10 failures that occur with frequency one half.
+
+[link math_toolkit.stat_tut.weg.neg_binom_eg.neg_binom_size_eg Worked Example.]
+
+This function uses numeric inversion of the geometric distribution
+to obtain the result: another interpretation of the result is that it finds
+the number of trials (failures) that will lead to an /alpha/ probability
+of observing /k/ failures or fewer.
+
+[h5 Estimating Number of Trials to Ensure a Maximum Number of Failures or Less]
+
+ static RealType find_maximum_number_of_trials(
+ RealType k, // number of failures.
+ RealType p, // success fraction.
+ RealType alpha); // probability threshold (0.05 equivalent to 95%).
+
+This functions estimates the maximum number of trials we can conduct and achieve
+a certain probability that [*k failures or fewer will be observed].
+
+[variablelist
+[[k][The maximum number of failures to be observed.]]
+[[p][The probability of ['success] for each trial.]]
+[[alpha][The maximum acceptable ['risk] that more than ['k] failures will be observed.]]
+]
+
+For example:
+
+ geometric_distribution<RealType>::find_maximum_number_of_trials(0, 1.0-1.0/1000000, 0.05);
+
+Returns the largest number of trials we can conduct and still be 95% sure
+of seeing no failures that occur with frequency one in one million.
+
+This function uses numeric inversion of the geometric distribution
+to obtain the result: another interpretation of the result, is that it finds
+the number of trials that will lead to an /alpha/ probability
+of observing more than k failures.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
+that are generic to all distributions are supported: __usual_accessors.
+
+However it's worth taking a moment to define what these actually mean in
+the context of this distribution:
+
+[table Meaning of the non-member accessors.
+[[Function][Meaning]]
+[[__pdf]
+ [The probability of obtaining [*exactly k failures] from /k/ trials
+ with success fraction p. For example:
+
+``pdf(geometric(p), k)``]]
+[[__cdf]
+ [The probability of obtaining [*k failures or fewer] from /k/ trials
+ with success fraction p and success on the last trial. For example:
+
+``cdf(geometric(p), k)``]]
+[[__ccdf]
+ [The probability of obtaining [*more than k failures] from /k/ trials
+ with success fraction p and success on the last trial. For example:
+
+``cdf(complement(geometric(p), k))``]]
+[[__quantile]
+ [The [*greatest] number of failures /k/ expected to be observed from /k/ trials
+ with success fraction /p/, at probability /P/. Note that the value returned
+ is a real-number, and not an integer. Depending on the use case you may
+ want to take either the floor or ceiling of the real result. For example:
+``quantile(geometric(p), P)``]]
+[[__quantile_c]
+ [The [*smallest] number of failures /k/ expected to be observed from /k/ trials
+ with success fraction /p/, at probability /P/. Note that the value returned
+ is a real-number, and not an integer. Depending on the use case you may
+ want to take either the floor or ceiling of the real result. For example:
+ ``quantile(complement(geometric(p), P))``]]
+]
+
+[h4 Accuracy]
+
+This distribution is implemented using the pow and exp functions, so most results
+are accurate within a few epsilon for the RealType.
+For extreme values of `double` /p/, for example 0.9999999999,
+accuracy can fall significantly, for example to 10 decimal digits (from 16).
+
+[h4 Implementation]
+
+In the following table, /p/ is the probability that any one trial will
+be successful (the success fraction), /k/ is the number of failures,
+/p/ is the probability and /q = 1-p/,
+/x/ is the given probability to estimate
+the expected number of failures using the quantile.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][pdf = p * pow(q, k)]]
+[[cdf][cdf = 1 - q[super k=1]]]
+[[cdf complement][exp(log1p(-p) * (k+1))]]
+[[quantile][k = log1p(-x) / log1p(-p) -1]]
+[[quantile from the complement][k = log(x) / log1p(-p) -1]]
+[[mean][(1-p)/p]]
+[[variance][(1-p)/p[sup2]]]
+[[mode][0]]
+[[skewness][(2-p)/[sqrt]q]]
+[[kurtosis][9+p[sup2]/q]]
+[[kurtosis excess][6 +p[sup2]/q]]
+[[parameter estimation member functions][See __negative_binomial_distrib]]
+[[`find_lower_bound_on_p`][See __negative_binomial_distrib]]
+[[`find_upper_bound_on_p`][See __negative_binomial_distrib]]
+[[`find_minimum_number_of_trials`][See __negative_binomial_distrib]]
+[[`find_maximum_number_of_trials`][See __negative_binomial_distrib]]
+]
+
+[endsect][/section:geometric_dist geometric]
+
+[/ geometric.qbk
+ Copyright 2010 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).
+]
+
diff --git a/doc/distributions/geometric_example.qbk b/doc/distributions/geometric_example.qbk
new file mode 100644
index 0000000..9405648
--- /dev/null
+++ b/doc/distributions/geometric_example.qbk
@@ -0,0 +1,20 @@
+[section:geometric_eg Geometric Distribution Examples]
+
+[import ../../example/geometric_examples.cpp]
+[geometric_eg1_1]
+[geometric_eg1_2]
+
+See full source C++ of this example at
+[@../../example/geometric_examples.cpp geometric_examples.cpp]
+
+[link math_toolkit.stat_tut.weg.neg_binom_eg.neg_binom_conf See negative_binomial confidence interval example.]
+
+[endsect] [/section:geometric_eg Geometric Distribution Examples]
+
+[/ geometric.qbk
+ Copyright 2010 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).
+]
+
diff --git a/doc/distributions/hyperexponential.qbk b/doc/distributions/hyperexponential.qbk
new file mode 100644
index 0000000..d2b2a1d
--- /dev/null
+++ b/doc/distributions/hyperexponential.qbk
@@ -0,0 +1,506 @@
+[section:hyperexponential_dist Hyperexponential Distribution]
+
+[import ../../example/hyperexponential_snips.cpp]
+[import ../../example/hyperexponential_more_snips.cpp]
+
+``#include <boost/math/distributions/hyperexponential.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <typename RealType = double,
+ typename ``__Policy`` = ``__policy_class`` >
+ class hyperexponential_distribution;
+
+ typedef hyperexponential_distribution<> hyperexponential;
+
+ template <typename RealType, typename ``__Policy``>
+ class hyperexponential_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ // Constructors:
+ hyperexponential_distribution(); // Default.
+
+ template <typename RateIterT, typename RateIterT2>
+ hyperexponential_distribution( // Default equal probabilities.
+ RateIterT const& rate_first,
+ RateIterT2 const& rate_last); // Rates using Iterators.
+
+ template <typename ProbIterT, typename RateIterT>
+ hyperexponential_distribution(ProbIterT prob_first, ProbIterT prob_last,
+ RateIterT rate_first, RateIterT rate_last); // Iterators.
+
+ template <typename ProbRangeT, typename RateRangeT>
+ hyperexponential_distribution(ProbRangeT const& prob_range,
+ RateRangeT const& rate_range); // Ranges.
+
+ template <typename RateRangeT>
+ hyperexponential_distribution(RateRangeT const& rate_range);
+
+ #if !defined(BOOST_NO_CXX11_HDR_INITIALIZER_LIST) // C++11 initializer lists supported.
+ hyperexponential_distribution(std::initializer_list<RealType> l1, std::initializer_list<RealType> l2);
+ hyperexponential_distribution(std::initializer_list<RealType> l1);
+ #endif
+
+ // Accessors:
+ std::size_t num_phases() const;
+ std::vector<RealType> probabilities() const;
+ std::vector<RealType> rates() const;
+ };
+
+ }} // namespaces
+
+[note An implementation-defined mechanism is provided to avoid
+ambiguity between constructors accepting ranges, iterators and constants as parameters.
+This should be transparent to the user.
+See below and the header file hyperexponential.hpp for details and explanatory comments.]
+
+The class type `hyperexponential_distribution` represents a [@http://en.wikipedia.org/wiki/Hyperexponential_distribution hyperexponential distribution].
+
+A /k/-phase hyperexponential distribution is a [@http://en.wikipedia.org/wiki/Continuous_probability_distribution continuous probability distribution] obtained as a mixture of /k/ [link math_toolkit.dist_ref.dists.exp_dist Exponential Distribution]s.
+It is also referred to as /mixed exponential distribution/ or parallel /k-phase exponential distribution/.
+
+A /k/-phase hyperexponential distribution is characterized by two parameters, namely a /phase probability vector/ ['[*[alpha]]=([alpha][sub 1],...,[alpha][sub k])] and a /rate vector/ ['[*[lambda]]=([lambda][sub 1],...,[lambda][sub k])].
+
+The [@http://en.wikipedia.org/wiki/Probability_density_function probability density function] for random variate /x/ in a hyperexponential distribution is given by:
+
+[equation hyperexponential_pdf]
+
+The following graph illustrates the PDF of the hyperexponential distribution with five different parameters, namely:
+
+# ['[*[alpha]]=(1.0)] and ['[*[lambda]]=(1.0)] (which degenerates to a simple exponential distribution),
+# ['[*[alpha]]=(0.1, 0.9)] and ['[*[lambda]]=(0.5, 1.5)],
+# ['[*[alpha]]=(0.9, 0.1)] and ['[*[lambda]]=(0.5, 1.5)],
+# ['[*[alpha]]=(0.2, 0.3, 0.5)] and ['[*[lambda]]=(0.5, 1.0, 1.5)],
+# ['[*[alpha]]=(0.5, 0.3, 0.2)] and ['[*[lambda]]=(0.5, 1.0, 1.5)].
+
+[graph hyperexponential_pdf]
+
+Also, the following graph illustrates the PDF of the hyperexponential distribution (solid lines) where only the /phase probability vector/ changes together with the PDF of the two limiting exponential distributions (dashed lines):
+
+# ['[*[alpha]]=(0.1, 0.9)] and ['[*[lambda]]=(0.5, 1.5)],
+# ['[*[alpha]]=(0.6, 0.4)] and ['[*[lambda]]=(0.5, 1.5)],
+# ['[*[alpha]]=(0.9, 0.1)] and ['[*[lambda]]=(0.5, 1.5)],
+# Exponential distribution with parameter ['[lambda]=0.5],
+# Exponential distribution with parameter ['[lambda]=1.5].
+
+As expected, as the first element ['[alpha][sub 1]] of the /phase probability vector/ approaches to /1/ (or, equivalently, ['[alpha][sub 2]] approaches to /0/), the resulting hyperexponential distribution nears the exponential distribution with parameter ['[lambda]=0.5].
+Conversely, as the first element ['[alpha][sub 2]] of the /phase probability vector/ approaches to /1/ (or, equivalently, ['[alpha][sub 1]] approaches to /0/), the resulting hyperexponential distribution nears the exponential distribution with parameter ['[lambda]=1.5].
+
+[graph hyperexponential_pdf_samerate]
+
+Finally, the following graph compares the PDF of the hyperexponential distribution with different number of phases but with the same mean value equal to /2/:
+
+# ['[*[alpha]]=(1.0)] and ['[*[lambda]]=(2.0)] (which degenerates to a simple exponential distribution),
+# ['[*[alpha]]=(0.5, 0.5)] and ['[*[lambda]]=(0.3, 1.5)],
+# ['[*[alpha]]=(1.0/3.0, 1.0/3.0, 1.0/3.0)] and ['[*[lambda]]=(0.2, 1.5, 3.0)],
+
+[graph hyperexponential_pdf_samemean]
+
+As can be noted, even if the three distributions have the same mean value, the two hyperexponential distributions have a /longer/ tail with respect to the one of the exponential distribution.
+Indeed, the hyperexponential distribution has a larger variability than the exponential distribution, thus resulting in a [@http://en.wikipedia.org/wiki/Coefficient_of_variation Coefficient of Variation] greater than /1/ (as opposed to the one of the exponential distribution which is exactly /1/).
+
+[h3 Applications]
+
+A /k/-phase hyperexponential distribution is frequently used in [@http://en.wikipedia.org/wiki/Queueing_theory queueing theory] to model the distribution of the superposition of /k/ independent events, like, for instance, the service time distribution of a queueing station with /k/ servers in parallel where the /i/-th server is chosen with probability ['[alpha][sub i]] and its service time distribution is an exponential distribution with rate ['[lambda][sub i]] (Allen,1990; Papadopolous et al.,1993; Trivedi,2002).
+
+For instance, CPUs service-time distribution in a computing system has often been observed to possess such a distribution (Rosin,1965).
+Also, the arrival of different types of customer to a single queueing station is often modeled as a hyperexponential distribution (Papadopolous et al.,1993).
+Similarly, if a product manufactured in several parallel assembly lines and the outputs are merged, the failure density of the overall product is likely to be hyperexponential (Trivedi,2002).
+
+Finally, since the hyperexponential distribution exhibits a high Coefficient of Variation (CoV), that is a CoV > 1, it is especially suited to fit empirical data with large CoV (Feitelson,2014; Wolski et al.,2013) and to approximate [@http://en.wikipedia.org/wiki/Long_tail long-tail probability distributions] (Feldmann et al.,1998).
+
+[/ Another possible example (work in progress):
+For instance, suppose that at the airport the company Foobar Airlines has a help desk with 3 different windows (servers) such that window A is for regional flights, window B is for international flights and window C is general customer care.
+From previous studies, it has been observed that each window is able to serve requests with the following timings:
+- window W1: 20 minutes, on average,
+- window W2: 30 minutes, on average, and
+- window W3: 10 minutes, on average.
+
+Furthermore, another airline company has a help desk with a single window.
+It has been observed that to the window can arrive three types of customers:
+- customer C1 (e.g., premium customer):
+- customer C2 (e.g., business customer):
+- customer C3 (e.g., regular customer):
+]
+
+[h3 Related distributions]
+
+* When the number of phases /k/ is equal to `1`, the hyperexponential distribution is simply an __exp_distrib.
+* When the /k/ rates are all equal to ['[lambda]], the hyperexponential distribution is simple an __exp_distrib with rate ['[lambda]].
+
+[h3 Examples]
+
+[h4 Lifetime of Appliances]
+
+Suppose a customer is buying an appliance and is choosing at random between an appliance with average lifetime of 10 years and an appliance with average lifetime of 12 years.
+Assuming the lifetime of this appliance follows an exponential distribution, the lifetime distribution of the purchased appliance can be modeled as a hyperexponential distribution with
+phase probability vector ['[*[alpha]]=(1/2,1/2)] and rate vector ['[*[lambda]]=(1/10,1/12)] (Wolfram,2014).
+
+In the rest of this section, we provide an example C++ implementation for computing the average lifetime and the probability that the appliance will work for more than 15 years.
+
+[hyperexponential_snip1]
+
+The resulting output is:
+
+ Average lifetime: 11 years
+ Probability that the appliance will work for more than 15 years: 0.254817
+
+
+[h4 Workloads of Private Cloud Computing Systems]
+
+[@http://en.wikipedia.org/wiki/Cloud_computing Cloud computing] has become a popular metaphor for dynamic and secure self-service access to computational and storage capabilities.
+In (Wolski et al.,2013), the authors analyze and model workloads gathered from enterprise-operated commercial [@http://en.wikipedia.org/wiki/Cloud_computing#Private_cloud private clouds] and show that 3-phase hyperexponential distributions (fitted using the [@http://en.wikipedia.org/wiki/Expectation%E2%80%93maximization_algorithm Expectation Maximization algorithm]) capture workload attributes accurately.
+
+In this type of computing system, user requests consist in demanding the provisioning of one or more [@http://en.wikipedia.org/wiki/Virtual_machine Virtual Machines] (VMs).
+In particular, in (Wolski et al.,2013) the workload experienced by each cloud system is a function of four distributions, one for each of the following workload attributes:
+
+* /Request Interarrival Time/: the amount of time until the next request,
+* /VM Lifetime/: the time duration over which a VM is provisioned to a physical machine,
+* /Request Size/: the number of VMs in the request, and
+* /Core Count/: the CPU core count requested for each VM.
+
+The authors assume that all VMs in a request have the same core count, but request sizes and core counts can vary from request to request.
+Moreover, all VMs within a request are assumed to have the same lifetime.
+Given these assumptions, the authors build a statistical model for the request interarrival time and VM lifetime attributes by fitting their respective data to a 3-phase hyperexponential distribution.
+
+In the following table, we show the sample mean and standard deviation (SD), in seconds, of the request interarrival time and of the VM lifetime distributions of the three datasets collected by authors:
+
+[table
+[[Dataset][Mean Request Interarrival Time (SD)][Mean Multi-core VM Lifetime (SD)][Mean Single-core VM Lifetime (SD)]]
+[[DS1][2202.1 (2.2e+04)][257173 (4.6e+05)][28754.4 (1.6e+05)]]
+[[DS2][41285.7 (1.1e+05)][144669.0 (7.9e+05)][599815.0 (1.7e+06)]]
+[[DS3][11238.8 (3.0e+04)][30739.2 (1.6e+05)][44447.8 (2.2e+05)]]
+]
+
+Whereas in the following table we show the hyperexponential distribution parameters resulting from the fit:
+
+[table
+[[Dataset][Request Interarrival Time][Multi-core VM Lifetime][Single-core VM Lifetime]]
+[[DS1][['[*[alpha]]=(0.34561,0.08648,0.56791), [*[lambda]]=(0.008,0.00005,0.02894)]][['[*[alpha]]=(0.24667,0.37948,0.37385), [*[lambda]]=(0.00004,0.000002,0.00059)]][['[*[alpha]]=(0.09325,0.22251,0.68424), [*[lambda]]=(0.000003,0.00109,0.00109)]]]
+[[DS2][['[*[alpha]]=(0.38881,0.18227,0.42892), [*[lambda]]=(0.000006,0.05228,0.00081)]][['[*[alpha]]=(0.42093,0.43960,0.13947), [*[lambda]]=(0.00186,0.00008,0.0000008)]][['[*[alpha]]=(0.44885,0.30675,0.2444), [*[lambda]]=(0.00143,0.00005,0.0000004)]]]
+[[DS3][['[*[alpha]]=(0.39442,0.24644,0.35914), [*[lambda]]=(0.00030,0.00003,0.00257)]][['[*[alpha]]=(0.37621,0.14838,0.47541), [*[lambda]]=(0.00498,0.000005,0.00022)]][['[*[alpha]]=(0.34131,0.12544,0.53325), [*[lambda]]=(0.000297,0.000003,0.00410)]]]
+]
+
+In the rest of this section, we provide an example C++ implementation for computing some statistical properties of the fitted distributions for each of the analyzed dataset.
+
+[hyperexponential_more_snip1]
+
+The resulting output (with floating-point precision set to 2) is:
+
+ ### DS1
+ * Fitted Request Interarrival Time
+ - Mean (SD): 2.2e+03 (8.1e+03) seconds.
+ - 99th Percentile: 4.3e+04 seconds.
+ - Probability that a VM will arrive within 30 minutes: 0.84
+ - Probability that a VM will arrive after 1 hour: 0.092
+ * Fitted Multi-core VM Lifetime
+ - Mean (SD): 2e+05 (3.9e+05) seconds.
+ - 99th Percentile: 1.8e+06 seconds.
+ - Probability that a VM will last for less than 1 month: 1
+ - Probability that a VM will last for more than 3 months: 6.7e-08
+ * Fitted Single-core VM Lifetime
+ - Mean (SD): 3.2e+04 (1.4e+05) seconds.
+ - 99th Percentile: 7.4e+05 seconds.
+ - Probability that a VM will last for less than 1 month: 1
+ - Probability that a VM will last for more than 3 months: 6.9e-12
+ ### DS2
+ * Fitted Request Interarrival Time
+ - Mean (SD): 6.5e+04 (1.3e+05) seconds.
+ - 99th Percentile: 6.1e+05 seconds.
+ - Probability that a VM will arrive within 30 minutes: 0.52
+ - Probability that a VM will arrive after 1 hour: 0.4
+ * Fitted Multi-core VM Lifetime
+ - Mean (SD): 1.8e+05 (6.4e+05) seconds.
+ - 99th Percentile: 3.3e+06 seconds.
+ - Probability that a VM will last for less than 1 month: 0.98
+ - Probability that a VM will last for more than 3 months: 0.00028
+ * Fitted Single-core VM Lifetime
+ - Mean (SD): 6.2e+05 (1.6e+06) seconds.
+ - 99th Percentile: 8e+06 seconds.
+ - Probability that a VM will last for less than 1 month: 0.91
+ - Probability that a VM will last for more than 3 months: 0.011
+ ### DS3
+ * Fitted Request Interarrival Time
+ - Mean (SD): 9.7e+03 (2.2e+04) seconds.
+ - 99th Percentile: 1.1e+05 seconds.
+ - Probability that a VM will arrive within 30 minutes: 0.53
+ - Probability that a VM will arrive after 1 hour: 0.36
+ * Fitted Multi-core VM Lifetime
+ - Mean (SD): 3.2e+04 (1e+05) seconds.
+ - 99th Percentile: 5.4e+05 seconds.
+ - Probability that a VM will last for less than 1 month: 1
+ - Probability that a VM will last for more than 3 months: 1.9e-18
+ * Fitted Single-core VM Lifetime
+ - Mean (SD): 4.3e+04 (1.6e+05) seconds.
+ - 99th Percentile: 8.4e+05 seconds.
+ - Probability that a VM will last for less than 1 month: 1
+ - Probability that a VM will last for more than 3 months: 9.3e-12
+
+[note The above results differ from the ones shown in Tables III, V, and VII of (Wolski et al.,2013).
+We carefully double-checked them with Wolfram Mathematica 10, which confirmed our results.]
+
+
+[h3 Member Functions]
+
+[h4 Default Constructor]
+
+ hyperexponential_distribution();
+
+Constructs a /1/-phase hyperexponential distribution (i.e., an exponential distribution) with rate `1`.
+
+
+[h4 Constructor from Iterators]
+
+ template <typename ProbIterT, typename RateIterT>
+ hyperexponential_distribution(ProbIterT prob_first, ProbIterT prob_last,
+ RateIterT rate_first, RateIterT rate_last);
+
+Constructs a hyperexponential distribution with /phase probability vector/ parameter given
+by the range defined by \[`prob_first`, `prob_last`) iterator pair, and /rate vector/ parameter
+given by the range defined by the \[`rate_first`, `rate_last`) iterator pair.
+
+[h5 Parameters]
+
+* `prob_first`, `prob_last`: the range of non-negative real elements representing the phase probabilities; elements are normalized to sum to unity.
+* `rate_first`, `rate_last`: the range of positive elements representing the rates.
+
+[h5 Type Requirements]
+
+[itemized_list [`ProbIterT`, `RateIterT`: must meet the requirements of the [@http://en.cppreference.com/w/cpp/concept/InputIterator InputIterator] concept.]]
+
+[h5 Example]
+
+[hyperexponential_snip2]
+
+[h4 Construction from Ranges/Containers]
+
+ template <typename ProbRangeT, typename RateRangeT>
+ hyperexponential_distribution(ProbRangeT const& prob_range,
+ RateRangeT const& rate_range);
+
+Constructs a hyperexponential distribution with /phase probability vector/ parameter
+given by the range defined by `prob_range`, and /rate vector/ parameter given by the range defined by `rate_range`.
+
+[note As an implementation detail, this constructor uses Boost's
+[@http://www.boost.org/doc/libs/release/libs/core/doc/html/core/enable_if.html enable_if/disable_if mechanism] to
+disambiguate between this and other 2-argument constructors. Refer to the source code for more details.]
+
+[h5 Parameters]
+
+* `prob_range`: the range of non-negative real elements representing the phase probabilities; elements are normalized to sum to unity.
+* `rate_range`: the range of positive real elements representing the rates.
+
+[h5 Type Requirements]
+
+[itemized_list [`ProbRangeT`, `RateRangeT`: must meet the requirements of the [@http://www.boost.org/doc/libs/release/libs/range/doc/html/range/concepts.html Range] concept:
+that includes native C++ arrays, standard library containers, or a std::pair or iterators.]]
+
+[h5 Examples]
+
+[hyperexponential_snip3]
+
+[h4 Construction with rates-iterators (and all phase probabilities equal)]
+
+ template <typename RateIterT, typename RateIterT2>
+ hyperexponential_distribution(RateIterT const& rate_first,
+ RateIterT2 const& rate_last);
+
+Constructs a hyperexponential distribution with /rate vector/ parameter given by the range defined by the
+\[`rate_first`, `rate_last`) iterator pair, and /phase probability vector/ set to the equal phase
+probabilities (i.e., to a vector of the same length `n` of the /rate vector/ and with each element set to `1.0/n`).
+
+[note As an implementation detail, this constructor uses Boost's
+[@http://www.boost.org/doc/libs/release/libs/core/doc/html/core/enable_if.html enable_if/disable_if mechanism] to
+disambiguate between this and other 2-argument constructors. Refer to the source code for more details.]
+
+[h5 Parameters]
+
+* `rate_first`, `rate_last`: the range of positive elements representing the rates.
+
+[h5 Type Requirements]
+
+[itemized_list [`RateIterT`, `RateIterT2`: must meet the requirements of the [@http://en.cppreference.com/w/cpp/concept/InputIterator InputIterator] concept.]]
+
+[h5 Example]
+
+[hyperexponential_snip4]
+
+[h4 Construction from a single range of rates (all phase probabilities will be equal)]
+
+ template <typename RateRangeT>
+ hyperexponential_distribution(RateRangeT const& rate_range);
+
+Constructs a hyperexponential distribution with /rate vector/ parameter given by the range defined by `rate_range`,
+and /phase probability vector/ set to the equal phase probabilities (i.e., to a vector of the same length
+`n` of the /rate vector/ and with each element set to `1.0/n`).
+
+[h5 Parameters]
+
+* `rate_range`: the range of positive real elements representing the rates.
+
+[h5 Type Requirements]
+
+[itemized_list [`RateRangeT`: must meet the requirements of the [@http://www.boost.org/doc/libs/release/libs/range/doc/html/range/concepts.html Range] concept: this includes
+native C++ array, standard library containers, and a `std::pair` of iterators.]]
+
+[h5 Examples]
+
+[hyperexponential_snip5]
+
+[h4 Construction from Initializer lists]
+
+ hyperexponential_distribution(std::initializer_list<RealType> l1, std::initializer_list<RealType> l2);
+
+Constructs a hyperexponential distribution with /phase probability vector/ parameter
+given by the [@http://en.cppreference.com/w/cpp/language/list_initialization brace-init-list] defined by `l1`,
+and /rate vector/ parameter given by the [@http://en.cppreference.com/w/cpp/language/list_initialization brace-init-list]
+defined by `l2`.
+
+[h5 Parameters]
+
+* `l1`: the brace-init-list of non-negative real elements representing the phase probabilities;
+elements are normalized to sum to unity.
+* `l2`: the brace-init-list of positive real elements representing the rates.
+
+The number of elements of the phase probabilities list and the rates list must be the same.
+
+[h5 Example]
+
+[hyperexponential_snip6]
+
+[h4 Construction from a single initializer list (all phase probabilities will be equal)]
+
+ hyperexponential_distribution(std::initializer_list<RealType> l1);
+
+Constructs a hyperexponential distribution with /rate vector/ parameter given by the
+[@http://en.cppreference.com/w/cpp/language/list_initialization brace-init-list] defined by `l1`, and
+/phase probability vector/ set to the equal phase probabilities (i.e., to a vector of the same length
+`n` of the /rate vector/ and with each element set to `1.0/n`).
+
+[h5 Parameters]
+
+* `l1`: the brace-init-list of non-negative real elements representing the phase probabilities; they are normalized to ensure that they sum to unity.
+
+[h5 Example]
+
+[hyperexponential_snip7]
+
+[h4 Accessors]
+
+ std::size_t num_phases() const;
+
+Gets the number of phases of this distribution (the size of both the rate and probability vectors).
+
+[h5 Return Value] An non-negative integer number representing the number of phases of this distribution.
+
+
+ std::vector<RealType> probabilities() const;
+
+Gets the /phase probability vector/ parameter of this distribution.
+
+[note The returned probabilities are the [*normalized] versions of the probability parameter values passed at construction time.]
+
+[h5 Return Value] A vector of non-negative real numbers representing the /phase probability vector/ parameter of this distribution.
+
+
+ std::vector<RealType> rates() const;
+
+Gets the /rate vector/ parameter of this distribution.
+
+[h5 Return Value] A vector of positive real numbers representing the /rate vector/ parameter of this distribution.
+
+[warning The return type of these functions is a vector-by-value. This is deliberate as we wish to hide the actual container
+used internally which may be subject to future changes (for example to facilitate vectorization of the cdf code etc).
+Users should note that some code that might otherwise have been expected to work does not.
+For example, an attempt to output the (normalized) probabilities:
+
+``
+std::copy(he.probabilities().begin(), he.probabilities().end(), std::ostream_iterator<double>(std::cout, " "));
+``
+
+fails at compile or runtime because iterator types are incompatible, but, for example,
+
+``
+std::cout << he.probabilities()[0] << ' ' << he.probabilities()[1] << std::endl;
+``
+
+outputs the expected values.
+
+In general if you want to access a member of the returned container, then assign to a variable first, and then access those
+members:
+
+``
+std::vector<double> t = he.probabilities();
+std::copy(t.begin(), t.end(), std::ostream_iterator<double>(std::cout, " "));
+``
+]
+
+[h3 Non-member Accessor Functions]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] that are generic to all distributions are supported: __usual_accessors.
+
+The formulae for calculating these are shown in the table below.
+
+
+[h3 Accuracy]
+
+The hyperexponential distribution is implemented in terms of the __exp_distrib and as such should have very small errors, usually an
+[@http://en.wikipedia.org/wiki/Machine_epsilon epsilon] or few.
+
+
+[h3 Implementation]
+
+In the following table:
+
+* ['[*[alpha]]=([alpha][sub 1],...,[alpha][sub k])] is the /phase probability vector/ parameter of the /k/-phase hyperexponential distribution,
+* ['[*[lambda]]=([lambda][sub 1],...,[lambda][sub k])] is the /rate vector/ parameter of the /k/-phase hyperexponential distribution,
+* /x/ is the random variate.
+
+[table
+[[Function][Implementation Notes]]
+[[support][['x] [isin] \[0,[infin])]]
+[[pdf][[equation hyperexponential_pdf]]]
+[[cdf][[equation hyperexponential_cdf]]]
+[[cdf complement][[equation hyperexponential_ccdf]]]
+[[quantile][No closed form available. Computed numerically.]]
+[[quantile from the complement][No closed form available. Computed numerically.]]
+[[mean][[equation hyperexponential_mean]]]
+[[variance][[equation hyperexponential_variance]]]
+[[mode][`0`]]
+[[skewness][[equation hyperexponential_skewness]]]
+[[kurtosis][[equation hyperexponential_kurtosis]]]
+[[kurtosis excess][kurtosis `- 3`]]
+]
+
+
+[h3 References]
+
+* A.O. Allen, /Probability, Statistics, and Queuing Theory with Computer Science Applications, Second Edition/, Academic Press, 1990.
+
+* D.G. Feitelson, /Workload Modeling for Computer Systems Performance Evaluation/, Cambridge University Press, 2014
+
+* A. Feldmann and W. Whitt, /Fitting mixtures of exponentials to long-tail distributions to analyze network performance models/, Performance Evaluation 31(3-4):245, doi:10.1016/S0166-5316(97)00003-5, 1998.
+
+* H.T. Papadopolous, C. Heavey and J. Browne, /Queueing Theory in Manufacturing Systems Analysis and Design/, Chapman & Hall/CRC, 1993, p. 35.
+
+* R.F. Rosin, /Determining a computing center environment/, Communications of the ACM 8(7):463-468, 1965.
+
+* K.S. Trivedi, /Probability and Statistics with Reliability, Queueing, and Computer Science Applications/, John Wiley & Sons, Inc., 2002.
+
+* Wikipedia, /Hyperexponential Distribution/, Online: [@http://en.wikipedia.org/wiki/Hyperexponential_distribution], 2014
+
+* R. Wolski and J. Brevik, /Using Parametric Models to Represent Private Cloud Workloads/, IEEE TSC, PrePrint, DOI: [@http://doi.ieeecomputersociety.org/10.1109/TSC.2013.48 10.1109/TSC.2013.48], 2013.
+
+* Wolfram Mathematica, /Hyperexponential Distribution/, Online: [@http://reference.wolfram.com/language/ref/HyperexponentialDistribution.html], 2014.
+
+[endsect][/section:hyperexponential_dist hyperexponential]
+
+[/ hyperexponential.qbk
+ Copyright 2014 Marco Guazzone (marco.guazzone@gmail.com)
+ 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).
+]
diff --git a/doc/distributions/hypergeometric.qbk b/doc/distributions/hypergeometric.qbk
new file mode 100644
index 0000000..f894189
--- /dev/null
+++ b/doc/distributions/hypergeometric.qbk
@@ -0,0 +1,229 @@
+[section:hypergeometric_dist Hypergeometric Distribution]
+
+``#include <boost/math/distributions/hypergeometric.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class hypergeometric_distribution;
+
+ template <class RealType, class Policy>
+ class hypergeometric_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+ // Construct:
+ hypergeometric_distribution(unsigned r, unsigned n, unsigned N);
+ // Accessors:
+ unsigned total()const;
+ unsigned defective()const;
+ unsigned sample_count()const;
+ };
+
+ typedef hypergeometric_distribution<> hypergeometric;
+
+ }} // namespaces
+
+The hypergeometric distribution describes the number of "events" /k/
+from a sample /n/ drawn from a total population /N/ ['without replacement].
+
+Imagine we have a sample of /N/ objects of which /r/ are "defective"
+and N-r are "not defective"
+(the terms "success\/failure" or "red\/blue" are also used). If we sample /n/
+items /without replacement/ then what is the probability that exactly
+/k/ items in the sample are defective? The answer is given by the pdf of the
+hypergeometric distribution `f(k; r, n, N)`, whilst the probability of
+/k/ defectives or fewer is given by F(k; r, n, N), where F(k) is the
+CDF of the hypergeometric distribution.
+
+[note Unlike almost all of the other distributions in this library,
+the hypergeometric distribution is strictly discrete: it can not be
+extended to real valued arguments of its parameters or random variable.]
+
+The following graph shows how the distribution changes as the proportion
+of "defective" items changes, while keeping the population and sample sizes
+constant:
+
+[graph hypergeometric_pdf_1]
+
+Note that since the distribution is symmetrical in parameters /n/ and /r/, if we
+change the sample size and keep the population and proportion "defective" the same
+then we obtain basically the same graphs:
+
+[graph hypergeometric_pdf_2]
+
+[h4 Member Functions]
+
+ hypergeometric_distribution(unsigned r, unsigned n, unsigned N);
+
+Constructs a hypergeometric distribution with a population of /N/ objects,
+of which /r/ are defective, and from which /n/ are sampled.
+
+ unsigned total()const;
+
+Returns the total number of objects /N/.
+
+ unsigned defective()const;
+
+Returns the number of objects /r/ in population /N/ which are defective.
+
+ unsigned sample_count()const;
+
+Returns the number of objects /n/ which are sampled from the population /N/.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
+that are generic to all distributions are supported: __usual_accessors.
+
+The domain of the random variable is the unsigned integers in the range
+\[max(0, n + r - N), min(n, r)\]. A __domain_error is raised if the
+random variable is outside this range, or is not an integral value.
+
+[caution
+The quantile function will by default return an integer result that has been
+/rounded outwards/. That is to say lower quantiles (where the probability is
+less than 0.5) are rounded downward, and upper quantiles (where the probability
+is greater than 0.5) are rounded upwards. 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 using
+[link math_toolkit.pol_overview Policies]. It is strongly
+recommended that you read the tutorial
+[link math_toolkit.pol_tutorial.understand_dis_quant
+Understanding Quantiles of Discrete Distributions] before
+using the quantile function on the Hypergeometric distribution. The
+[link math_toolkit.pol_ref.discrete_quant_ref reference docs]
+describe how to change the rounding policy
+for these distributions.
+
+However, note that the implementation method of the quantile function
+always returns an integral value, therefore attempting to use a __Policy
+that requires (or produces) a real valued result will result in a
+compile time error.
+] [/ caution]
+
+
+[h4 Accuracy]
+
+For small N such that
+`N < boost::math::max_factorial<RealType>::value` then table based
+lookup of the results gives an accuracy to a few epsilon.
+`boost::math::max_factorial<RealType>::value` is 170 at double or long double
+precision.
+
+For larger N such that `N < boost::math::prime(boost::math::max_prime)`
+then only basic arithmetic is required for the calculation
+and the accuracy is typically < 20 epsilon. This takes care of N
+up to 104729.
+
+For `N > boost::math::prime(boost::math::max_prime)` then accuracy quickly
+degrades, with 5 or 6 decimal digits being lost for N = 110000.
+
+In general for very large N, the user should expect to lose log[sub 10]N
+decimal digits of precision during the calculation, with the results
+becoming meaningless for N >= 10[super 15].
+
+[h4 Testing]
+
+There are three sets of tests: our implementation is tested against a table of values
+produced by Mathematica's implementation of this distribution. We also sanity check
+our implementation against some spot values computed using the online calculator
+here [@http://stattrek.com/Tables/Hypergeometric.aspx http://stattrek.com/Tables/Hypergeometric.aspx].
+Finally we test accuracy against some high precision test data using
+this implementation and NTL::RR.
+
+[h4 Implementation]
+
+The PDF can be calculated directly using the formula:
+
+[equation hypergeometric1]
+
+However, this can only be used directly when the largest of the factorials
+is guaranteed not to overflow the floating point representation used.
+This formula is used directly when `N < max_factorial<RealType>::value`
+in which case table lookup of the factorials gives a rapid and accurate
+implementation method.
+
+For larger /N/ the method described in
+"An Accurate Computation of the Hypergeometric Distribution Function",
+Trong Wu, ACM Transactions on Mathematical Software, Vol. 19, No. 1,
+March 1993, Pages 33-43 is used. The method relies on the fact that
+there is an easy method for factorising a factorial into the product
+of prime numbers:
+
+[equation hypergeometric2]
+
+Where p[sub i] is the i'th prime number, and e[sub i] is a small
+positive integer or zero, which can be calculated via:
+
+[equation hypergeometric3]
+
+Further we can combine the factorials in the expression for the PDF
+to yield the PDF directly as the product of prime numbers:
+
+[equation hypergeometric4]
+
+With this time the exponents e[sub i] being either positive, negative
+or zero. Indeed such a degree of cancellation occurs in the calculation
+of the e[sub i] that many are zero, and typically most have a magnitude
+or no more than 1 or 2.
+
+Calculation of the product of the primes requires some care to prevent
+numerical overflow, we use a novel recursive method which splits the
+calculation into a series of sub-products, with a new sub-product
+started each time the next multiplication would cause either overflow
+or underflow. The sub-products are stored in a linked list on the
+program stack, and combined in an order that will guarantee no overflow
+or unnecessary-underflow once the last sub-product has been calculated.
+
+This method can be used as long as N is smaller than the largest prime
+number we have stored in our table of primes (currently 104729). The method
+is relatively slow (calculating the exponents requires the most time), but
+requires only a small number of arithmetic operations to
+calculate the result (indeed there is no shorter method involving only basic
+arithmetic once the exponents have been found), the method is therefore
+much more accurate than the alternatives.
+
+For much larger N, we can calculate the PDF from the factorials using
+either lgamma, or by directly combining lanczos approximations to avoid
+calculating via logarithms. We use the latter method, as it is usually
+1 or 2 decimal digits more accurate than computing via logarithms with
+lgamma. However, in this area where N > 104729, the user should expect
+to lose around log[sub 10]N decimal digits during the calculation in
+the worst case.
+
+The CDF and its complement is calculated by directly summing the PDF's.
+We start by deciding whether the CDF, or its complement, is likely to be
+the smaller of the two and then calculate the PDF at /k/ (or /k+1/ if we're
+calculating the complement) and calculate successive PDF values via the
+recurrence relations:
+
+[equation hypergeometric5]
+
+Until we either reach the end of the distributions domain, or the next
+PDF value to be summed would be too small to affect the result.
+
+The quantile is calculated in a similar manner to the CDF: we first guess
+which end of the distribution we're nearer to, and then sum PDFs starting
+from the end of the distribution this time, until we have some value /k/ that
+gives the required CDF.
+
+The median is simply the quantile at 0.5, and the remaining properties are
+calculated via:
+
+[equation hypergeometric6]
+
+[endsect]
+
+[/ hypergeometric.qbk
+ Copyright 2008 John Maddock.
+ 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).
+]
diff --git a/doc/distributions/inverse_chi_squared.qbk b/doc/distributions/inverse_chi_squared.qbk
new file mode 100644
index 0000000..4c1f9f9
--- /dev/null
+++ b/doc/distributions/inverse_chi_squared.qbk
@@ -0,0 +1,176 @@
+[section:inverse_chi_squared_dist Inverse Chi Squared Distribution]
+
+``#include <boost/math/distributions/inverse_chi_squared.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class inverse_chi_squared_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ inverse_chi_squared_distribution(RealType df = 1); // Not explicitly scaled, default 1/df.
+ inverse_chi_squared_distribution(RealType df, RealType scale = 1/df); // Scaled.
+
+ RealType degrees_of_freedom()const; // Default 1.
+ RealType scale()const; // Optional scale [xi] (variance), default 1/degrees_of_freedom.
+ };
+
+ }} // namespace boost // namespace math
+
+The inverse chi squared distribution is a continuous probability distribution
+of the *reciprocal* of a variable distributed according to the chi squared distribution.
+
+The sources below give confusingly different formulae
+using different symbols for the distribution pdf,
+but they are all the same, or related by a change of variable, or choice of scale.
+
+Two constructors are available to implement both the scaled and (implicitly) unscaled versions.
+
+The main version has an explicit scale parameter which implements the
+[@http://en.wikipedia.org/wiki/Scaled-inverse-chi-square_distribution scaled inverse chi_squared distribution].
+
+A second version has an implicit scale = 1/degrees of freedom and gives the 1st definition in the
+[@http://en.wikipedia.org/wiki/Inverse-chi-square_distribution Wikipedia inverse chi_squared distribution].
+The 2nd Wikipedia inverse chi_squared distribution definition can be implemented
+by explicitly specifying a scale = 1.
+
+Both definitions are also available in Wolfram Mathematica and in __R (geoR) with default scale = 1/degrees of freedom.
+
+See
+
+* Inverse chi_squared distribution [@http://en.wikipedia.org/wiki/Inverse-chi-square_distribution]
+* Scaled inverse chi_squared distribution[@http://en.wikipedia.org/wiki/Scaled-inverse-chi-square_distribution]
+* R inverse chi_squared distribution functions [@http://hosho.ees.hokudai.ac.jp/~kubo/Rdoc/library/geoR/html/InvChisquare.html R ]
+* Inverse chi_squared distribution functions [@http://mathworld.wolfram.com/InverseChi-SquaredDistribution.html Weisstein, Eric W. "Inverse Chi-Squared Distribution." From MathWorld--A Wolfram Web Resource.]
+* Inverse chi_squared distribution reference [@http://reference.wolfram.com/mathematica/ref/InverseChiSquareDistribution.html Weisstein, Eric W. "Inverse Chi-Squared Distribution reference." From Wolfram Mathematica.]
+
+The inverse_chi_squared distribution is used in
+[@http://en.wikipedia.org/wiki/Bayesian_statistics Bayesian statistics]:
+the scaled inverse chi-square is conjugate prior for the normal distribution
+with known mean, model parameter [sigma][pow2] (variance).
+
+See [@http://en.wikipedia.org/wiki/Conjugate_prior conjugate priors including a table of distributions and their priors.]
+
+See also __inverse_gamma_distrib and __chi_squared_distrib.
+
+The inverse_chi_squared distribution is a special case of a inverse_gamma distribution
+with [nu] (degrees_of_freedom) shape ([alpha]) and scale ([beta]) where
+
+__spaces [alpha]= [nu] /2 and [beta] = [frac12].
+
+[note This distribution *does* provide the typedef:
+
+``typedef inverse_chi_squared_distribution<double> inverse_chi_squared;``
+
+If you want a `double` precision inverse_chi_squared distribution you can use
+
+``boost::math::inverse_chi_squared_distribution<>``
+
+or you can write `inverse_chi_squared my_invchisqr(2, 3);`]
+
+For degrees of freedom parameter [nu],
+the (*unscaled*) inverse chi_squared distribution is defined by the probability density function (PDF):
+
+__spaces f(x;[nu]) = 2[super -[nu]/2] x[super -[nu]/2-1] e[super -1/2x] / [Gamma]([nu]/2)
+
+and Cumulative Density Function (CDF)
+
+__spaces F(x;[nu]) = [Gamma]([nu]/2, 1/2x) / [Gamma]([nu]/2)
+
+For degrees of freedom parameter [nu] and scale parameter [xi],
+the *scaled* inverse chi_squared distribution is defined by the probability density function (PDF):
+
+__spaces f(x;[nu], [xi]) = ([xi][nu]/2)[super [nu]/2] e[super -[nu][xi]/2x] x[super -1-[nu]/2] / [Gamma]([nu]/2)
+
+and Cumulative Density Function (CDF)
+
+__spaces F(x;[nu], [xi]) = [Gamma]([nu]/2, [nu][xi]/2x) / [Gamma]([nu]/2)
+
+The following graphs illustrate how the PDF and CDF of the inverse chi_squared distribution
+varies for a few values of parameters [nu] and [xi]:
+
+[graph inverse_chi_squared_pdf] [/.png or .svg]
+
+[graph inverse_chi_squared_cdf]
+
+[h4 Member Functions]
+
+ inverse_chi_squared_distribution(RealType df = 1); // Implicitly scaled 1/df.
+ inverse_chi_squared_distribution(RealType df = 1, RealType scale); // Explicitly scaled.
+
+Constructs an inverse chi_squared distribution with [nu] degrees of freedom ['df],
+and scale ['scale] with default value 1\/df.
+
+Requires that the degrees of freedom [nu] parameter is greater than zero, otherwise calls
+__domain_error.
+
+ RealType degrees_of_freedom()const;
+
+Returns the degrees_of_freedom [nu] parameter of this distribution.
+
+ RealType scale()const;
+
+Returns the scale [xi] parameter of this distribution.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] that are generic to all
+distributions are supported: __usual_accessors.
+
+The domain of the random variate is \[0,+[infin]\].
+[note Unlike some definitions, this implementation supports a random variate
+equal to zero as a special case, returning zero for both pdf and cdf.]
+
+[h4 Accuracy]
+
+The inverse gamma distribution is implemented in terms of the
+incomplete gamma functions like the __inverse_gamma_distrib that use
+__gamma_p and __gamma_q and their inverses __gamma_p_inv and __gamma_q_inv:
+refer to the accuracy data for those functions for more information.
+But in general, gamma (and thus inverse gamma) results are often accurate to a few epsilon,
+>14 decimal digits accuracy for 64-bit double.
+unless iteration is involved, as for the estimation of degrees of freedom.
+
+[h4 Implementation]
+
+In the following table [nu] is the degrees of freedom parameter and
+[xi] is the scale parameter of the distribution,
+/x/ is the random variate, /p/ is the probability and /q = 1-p/ its complement.
+Parameters [alpha] for shape and [beta] for scale
+are used for the inverse gamma function: [alpha] = [nu]/2 and [beta] = [nu] * [xi]/2.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Using the relation: pdf = __gamma_p_derivative([alpha], [beta]/ x, [beta]) / x * x ]]
+[[cdf][Using the relation: p = __gamma_q([alpha], [beta] / x) ]]
+[[cdf complement][Using the relation: q = __gamma_p([alpha], [beta] / x) ]]
+[[quantile][Using the relation: x = [beta][space]/ __gamma_q_inv([alpha], p) ]]
+[[quantile from the complement][Using the relation: x = [alpha][space]/ __gamma_p_inv([alpha], q) ]]
+[[mode][[nu] * [xi] / ([nu] + 2) ]]
+[[median][no closed form analytic equation is known, but is evaluated as quantile(0.5)]]
+[[mean][[nu][xi] / ([nu] - 2) for [nu] > 2, else a __domain_error]]
+[[variance][2 [nu][pow2] [xi][pow2] / (([nu] -2)[pow2] ([nu] -4)) for [nu] >4, else a __domain_error]]
+[[skewness][4 [sqrt]2 [sqrt]([nu]-4) /([nu]-6) for [nu] >6, else a __domain_error ]]
+[[kurtosis_excess][12 * (5[nu] - 22) / (([nu] - 6) * ([nu] - 8)) for [nu] >8, else a __domain_error]]
+[[kurtosis][3 + 12 * (5[nu] - 22) / (([nu] - 6) * ([nu]-8)) for [nu] >8, else a __domain_error]]
+] [/table]
+
+[h4 References]
+
+# Bayesian Data Analysis, Andrew Gelman, John B. Carlin, Hal S. Stern, Donald B. Rubin,
+ISBN-13: 978-1584883883, Chapman & Hall; 2 edition (29 July 2003).
+
+# Bayesian Computation with R, Jim Albert, ISBN-13: 978-0387922973, Springer; 2nd ed. edition (10 Jun 2009)
+
+[endsect] [/section:inverse_chi_squared_dist Inverse chi_squared Distribution]
+
+[/
+ Copyright 2010 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).
+]
\ No newline at end of file
diff --git a/doc/distributions/inverse_chi_squared_eg.qbk b/doc/distributions/inverse_chi_squared_eg.qbk
new file mode 100644
index 0000000..067c746
--- /dev/null
+++ b/doc/distributions/inverse_chi_squared_eg.qbk
@@ -0,0 +1,32 @@
+
+[section:inverse_chi_squared_eg Inverse Chi-Squared Distribution Bayes Example]
+
+[import ../../example/inverse_chi_squared_bayes_eg.cpp]
+[inverse_chi_squared_bayes_eg_1]
+[inverse_chi_squared_bayes_eg_output_1]
+[inverse_chi_squared_bayes_eg_2]
+[inverse_chi_squared_bayes_eg_output_2]
+[inverse_chi_squared_bayes_eg_3]
+[inverse_chi_squared_bayes_eg_output_3]
+[inverse_chi_squared_bayes_eg_4]
+[inverse_chi_squared_bayes_eg_output_4]
+
+[inverse_chi_squared_bayes_eg_5]
+
+A full sample output is:
+[inverse_chi_squared_bayes_eg_output]
+
+(See also the reference documentation for the __inverse_chi_squared_distrib.)
+
+See the full source C++ of this example at
+[@../../example/inverse_chi_squared_bayes_eg.cpp]
+
+[endsect] [/section:inverse_chi_squared_eg Inverse Chi-Squared Distribution Bayes Example]
+
+[/
+ Copyright 2011 Paul A. Bristow and Thomas Mang.
+ 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).
+]
+
diff --git a/doc/distributions/inverse_gamma.qbk b/doc/distributions/inverse_gamma.qbk
new file mode 100644
index 0000000..0f8afea
--- /dev/null
+++ b/doc/distributions/inverse_gamma.qbk
@@ -0,0 +1,129 @@
+[section:inverse_gamma_dist Inverse Gamma Distribution]
+
+``#include <boost/math/distributions/inverse_gamma.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class inverse_gamma_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ inverse_gamma_distribution(RealType shape, RealType scale = 1)
+
+ RealType shape()const;
+ RealType scale()const;
+ };
+
+ }} // namespaces
+
+The inverse_gamma distribution is a continuous probability distribution
+of the reciprocal of a variable distributed according to the gamma distribution.
+
+The inverse_gamma distribution is used in Bayesian statistics.
+
+See [@http://en.wikipedia.org/wiki/Inverse-gamma_distribution inverse gamma distribution].
+
+[@http://rss.acs.unt.edu/Rdoc/library/pscl/html/igamma.html R inverse gamma distribution functions].
+
+[@http://reference.wolfram.com/mathematica/ref/InverseGammaDistribution.html Wolfram inverse gamma distribution].
+
+See also __gamma_distrib.
+
+
+[note
+In spite of potential confusion with the inverse gamma function, this
+distribution *does* provide the typedef:
+
+``typedef inverse_gamma_distribution<double> gamma;``
+
+If you want a `double` precision gamma distribution you can use
+
+``boost::math::inverse_gamma_distribution<>``
+
+or you can write `inverse_gamma my_ig(2, 3);`]
+
+For shape parameter [alpha] and scale parameter [beta], it is defined
+by the probability density function (PDF):
+
+__spaces f(x;[alpha], [beta]) = [beta][super [alpha]] * (1/x) [super [alpha]+1] exp(-[beta]/x) / [Gamma]([alpha])
+
+and cumulative density function (CDF)
+
+__spaces F(x;[alpha], [beta]) = [Gamma]([alpha], [beta]/x) / [Gamma]([alpha])
+
+The following graphs illustrate how the PDF and CDF of the inverse gamma distribution
+varies as the parameters vary:
+
+[graph inverse_gamma_pdf] [/png or svg]
+
+[graph inverse_gamma_cdf]
+
+[h4 Member Functions]
+
+ inverse_gamma_distribution(RealType shape = 1, RealType scale = 1);
+
+Constructs an inverse gamma distribution with shape [alpha] and scale [beta].
+
+Requires that the shape and scale parameters are greater than zero, otherwise calls
+__domain_error.
+
+ RealType shape()const;
+
+Returns the [alpha] shape parameter of this inverse gamma distribution.
+
+ RealType scale()const;
+
+Returns the [beta] scale parameter of this inverse gamma distribution.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] that are generic to all
+distributions are supported: __usual_accessors.
+
+The domain of the random variate is \[0,+[infin]\].
+[note Unlike some definitions, this implementation supports a random variate
+equal to zero as a special case, returning zero for pdf and cdf.]
+
+[h4 Accuracy]
+
+The inverse gamma distribution is implemented in terms of the
+incomplete gamma functions __gamma_p and __gamma_q and their
+inverses __gamma_p_inv and __gamma_q_inv: refer to the accuracy
+data for those functions for more information.
+But in general, inverse_gamma results are accurate to a few epsilon,
+>14 decimal digits accuracy for 64-bit double.
+
+[h4 Implementation]
+
+In the following table [alpha] is the shape parameter of the distribution,
+[alpha][space] is its scale parameter, /x/ is the random variate, /p/ is the probability
+and /q = 1-p/.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Using the relation: pdf = __gamma_p_derivative([alpha], [beta]/ x, [beta]) / x * x ]]
+[[cdf][Using the relation: p = __gamma_q([alpha], [beta] / x) ]]
+[[cdf complement][Using the relation: q = __gamma_p([alpha], [beta] / x) ]]
+[[quantile][Using the relation: x = [beta][space]/ __gamma_q_inv([alpha], p) ]]
+[[quantile from the complement][Using the relation: x = [alpha][space]/ __gamma_p_inv([alpha], q) ]]
+[[mode][[beta] / ([alpha] + 1) ]]
+[[median][no analytic equation is known, but is evaluated as quantile(0.5)]]
+[[mean][[beta] / ([alpha] - 1) for [alpha] > 1, else a __domain_error]]
+[[variance][([beta] * [beta]) / (([alpha] - 1) * ([alpha] - 1) * ([alpha] - 2)) for [alpha] >2, else a __domain_error]]
+[[skewness][4 * sqrt ([alpha] -2) / ([alpha] -3) for [alpha] >3, else a __domain_error]]
+[[kurtosis_excess][(30 * [alpha] - 66) / (([alpha]-3)*([alpha] - 4)) for [alpha] >4, else a __domain_error]]
+] [/table]
+
+[endsect][/section:inverse_gamma_dist Inverse Gamma Distribution]
+
+[/
+ Copyright 2010 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).
+]
+
diff --git a/doc/distributions/inverse_gamma_example.qbk b/doc/distributions/inverse_gamma_example.qbk
new file mode 100644
index 0000000..3feaa26
--- /dev/null
+++ b/doc/distributions/inverse_gamma_example.qbk
@@ -0,0 +1,15 @@
+
+[section:inverse_gamma_eg Inverse Gamma Distribution Bayes Example]
+
+TODO
+
+[endsect] [/section:inverse_gamma_eg Inverse Gamma Distribution Bayes Example]
+
+
+[/
+ Copyright 2006, 2010 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).
+]
+
diff --git a/doc/distributions/inverse_gaussian.qbk b/doc/distributions/inverse_gaussian.qbk
new file mode 100644
index 0000000..612801f
--- /dev/null
+++ b/doc/distributions/inverse_gaussian.qbk
@@ -0,0 +1,171 @@
+[section:inverse_gaussian_dist Inverse Gaussian (or Inverse Normal) Distribution]
+
+``#include <boost/math/distributions/inverse_gaussian.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class inverse_gaussian_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ inverse_gaussian_distribution(RealType mean = 1, RealType scale = 1);
+
+ RealType mean()const; // mean default 1.
+ RealType scale()const; // Optional scale, default 1 (unscaled).
+ RealType shape()const; // Shape = scale/mean.
+ };
+ typedef inverse_gaussian_distribution<double> inverse_gaussian;
+
+ }} // namespace boost // namespace math
+
+The Inverse Gaussian distribution distribution is a continuous probability distribution.
+
+The distribution is also called 'normal-inverse Gaussian distribution',
+and 'normal Inverse' distribution.
+
+It is also convenient to provide unity as default for both mean and scale.
+This is the Standard form for all distributions.
+The Inverse Gaussian distribution was first studied in relation to Brownian motion.
+In 1956 M.C.K. Tweedie used the name Inverse Gaussian because there is an inverse relationship
+between the time to cover a unit distance and distance covered in unit time.
+The inverse Gaussian is one of family of distributions that have been called the
+[@http://en.wikipedia.org/wiki/Tweedie_distributions Tweedie distributions].
+
+(So ['inverse] in the name may mislead: it does [*not] relate to the inverse of a distribution).
+
+The tails of the distribution decrease more slowly than the normal distribution.
+It is therefore suitable to model phenomena
+where numerically large values are more probable than is the case for the normal distribution.
+For stock market returns and prices, a key characteristic is that it models
+that extremely large variations from typical (crashes) can occur
+even when almost all (normal) variations are small.
+
+Examples are returns from financial assets and turbulent wind speeds.
+
+The normal-inverse Gaussian distributions form
+a subclass of the generalised hyperbolic distributions.
+
+See
+[@http://en.wikipedia.org/wiki/Normal-inverse_Gaussian_distribution distribution].
+[@http://mathworld.wolfram.com/InverseGaussianDistribution.html
+ Weisstein, Eric W. "Inverse Gaussian Distribution." From MathWorld--A Wolfram Web Resource.]
+
+If you want a `double` precision inverse_gaussian distribution you can use
+
+``boost::math::inverse_gaussian_distribution<>``
+
+or, more conveniently, you can write
+
+ using boost::math::inverse_gaussian;
+ inverse_gaussian my_ig(2, 3);
+
+For mean parameters [mu] and scale (also called precision) parameter [lambda],
+and random variate x,
+the inverse_gaussian distribution is defined by the probability density function (PDF):
+
+__spaces f(x;[mu], [lambda]) = [sqrt]([lambda]/2[pi]x[super 3]) e[super -[lambda](x-[mu])[sup2]/2[mu][sup2]x]
+
+and Cumulative Density Function (CDF):
+
+__spaces F(x;[mu], [lambda]) = [Phi]{[sqrt]([lambda]/x) (x/[mu]-1)} + e[super 2[mu]/[lambda]] [Phi]{-[sqrt]([lambda]/[mu]) (1+x/[mu])}
+
+where [Phi] is the standard normal distribution CDF.
+
+The following graphs illustrate how the PDF and CDF of the inverse_gaussian distribution
+varies for a few values of parameters [mu] and [lambda]:
+
+[graph inverse_gaussian_pdf] [/.png or .svg]
+
+[graph inverse_gaussian_cdf]
+
+Tweedie also provided 3 other parameterisations where ([mu] and [lambda])
+are replaced by their ratio [phi] = [lambda]/[mu] and by 1/[mu]:
+these forms may be more suitable for Bayesian applications.
+These can be found on Seshadri, page 2 and are also discussed by Chhikara and Folks on page 105.
+Another related parameterisation, the __wald_distrib (where mean [mu] is unity) is also provided.
+
+[h4 Member Functions]
+
+ inverse_gaussian_distribution(RealType df = 1, RealType scale = 1); // optionally scaled.
+
+Constructs an inverse_gaussian distribution with [mu] mean,
+and scale [lambda], with both default values 1.
+
+Requires that both the mean [mu] parameter and scale [lambda] are greater than zero,
+otherwise calls __domain_error.
+
+ RealType mean()const;
+
+Returns the mean [mu] parameter of this distribution.
+
+ RealType scale()const;
+
+Returns the scale [lambda] parameter of this distribution.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] that are generic to all
+distributions are supported: __usual_accessors.
+
+The domain of the random variate is \[0,+[infin]).
+[note Unlike some definitions, this implementation supports a random variate
+equal to zero as a special case, returning zero for both pdf and cdf.]
+
+[h4 Accuracy]
+
+The inverse_gaussian distribution is implemented in terms of the
+exponential function and standard normal distribution ['N]0,1 [Phi] :
+refer to the accuracy data for those functions for more information.
+But in general, gamma (and thus inverse gamma) results are often accurate to a few epsilon,
+>14 decimal digits accuracy for 64-bit double.
+
+[h4 Implementation]
+
+In the following table [mu] is the mean parameter and
+[lambda] is the scale parameter of the inverse_gaussian distribution,
+/x/ is the random variate, /p/ is the probability and /q = 1-p/ its complement.
+Parameters [mu] for shape and [lambda] for scale
+are used for the inverse gaussian function.
+
+[table
+[[Function] [Implementation Notes] ]
+[[pdf] [ [sqrt]([lambda]/ 2[pi]x[super 3]) e[super -[lambda](x - [mu])[sup2]/ 2[mu][sup2]x]]]
+[[cdf][ [Phi]{[sqrt]([lambda]/x) (x/[mu]-1)} + e[super 2[mu]/[lambda]] [Phi]{-[sqrt]([lambda]/[mu]) (1+x/[mu])} ]]
+[[cdf complement] [using complement of [Phi] above.] ]
+[[quantile][No closed form known. Estimated using a guess refined by Newton-Raphson iteration.]]
+[[quantile from the complement][No closed form known. Estimated using a guess refined by Newton-Raphson iteration.]]
+[[mode][[mu] {[sqrt](1+9[mu][sup2]/4[lambda][sup2])[sup2] - 3[mu]/2[lambda]} ]]
+[[median][No closed form analytic equation is known, but is evaluated as quantile(0.5)]]
+[[mean][[mu]] ]
+[[variance][[mu][cubed]/[lambda]] ]
+[[skewness][3 [sqrt] ([mu]/[lambda])] ]
+[[kurtosis_excess][15[mu]/[lambda]] ]
+[[kurtosis][12[mu]/[lambda]] ]
+] [/table]
+
+[h4 References]
+
+#Wald, A. (1947). Sequential analysis. Wiley, NY.
+#The Inverse Gaussian distribution : theory, methodology, and applications, Raj S. Chhikara, J. Leroy Folks. ISBN 0824779975 (1989).
+#The Inverse Gaussian distribution : statistical theory and applications, Seshadri, V , ISBN - 0387986189 (pbk) (Dewey 519.2) (1998).
+#[@http://docs.scipy.org/doc/numpy/reference/generated/numpy.random.wald.html Numpy and Scipy Documentation].
+#[@http://bm2.genes.nig.ac.jp/RGM2/R_current/library/statmod/man/invgauss.html R statmod invgauss functions].
+#[@http://cran.r-project.org/web/packages/SuppDists/index.html R SuppDists invGauss functions].
+(Note that these R implementations names differ in case).
+#[@http://www.statsci.org/s/invgauss.html StatSci.org invgauss help].
+#[@http://www.statsci.org/s/invgauss.statSci.org invgauss R source].
+#[@http://www.biostat.wustl.edu/archives/html/s-news/2001-12/msg00144.html pwald, qwald].
+#[@http://www.brighton-webs.co.uk/distributions/wald.asp Brighton Webs wald].
+
+[endsect] [/section:inverse_gaussian_dist Inverse Gaussiann Distribution]
+
+[/
+ Copyright 2010 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).
+]
\ No newline at end of file
diff --git a/doc/distributions/laplace.qbk b/doc/distributions/laplace.qbk
new file mode 100644
index 0000000..e62cc21
--- /dev/null
+++ b/doc/distributions/laplace.qbk
@@ -0,0 +1,141 @@
+[section:laplace_dist Laplace Distribution]
+
+``#include <boost/math/distributions/laplace.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class laplace_distribution;
+
+ typedef laplace_distribution<> laplace;
+
+ template <class RealType, class ``__Policy``>
+ class laplace_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+ // Construct:
+ laplace_distribution(RealType location = 0, RealType scale = 1);
+ // Accessors:
+ RealType location()const;
+ RealType scale()const;
+ };
+
+ }} // namespaces
+
+Laplace distribution is the distribution of differences between two independent variates
+with identical exponential distributions (Abramowitz and Stegun 1972, p. 930).
+It is also called the double exponential distribution.
+
+[/ Wikipedia definition is The difference between two independent identically distributed
+exponential random variables is governed by a Laplace distribution.]
+
+For location parameter [mu][space] and scale parameter [sigma][space], it is defined by the
+probability density function:
+
+[equation laplace_pdf]
+
+The location and scale parameters are equivalent to the mean and
+standard deviation of the normal or Gaussian distribution.
+
+The following graph illustrates the effect of the
+parameters [mu][space] and [sigma][space] on the PDF.
+Note that the domain of the random variable remains
+\[-[infin],+[infin]\] irrespective of the value of the location parameter:
+
+[graph laplace_pdf]
+
+[h4 Member Functions]
+
+ laplace_distribution(RealType location = 0, RealType scale = 1);
+
+Constructs a laplace distribution with location /location/ and
+scale /scale/.
+
+The location parameter is the same as the mean of the random variate.
+
+The scale parameter is proportional to the standard deviation of the random variate.
+
+Requires that the scale parameter is greater than zero, otherwise calls
+__domain_error.
+
+ RealType location()const;
+
+Returns the /location/ parameter of this distribution.
+
+ RealType scale()const;
+
+Returns the /scale/ parameter of this distribution.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] that are generic to all
+distributions are supported: __usual_accessors.
+
+The domain of the random variable is \[-[infin],+[infin]\].
+
+[h4 Accuracy]
+
+The laplace distribution is implemented in terms of the
+standard library log and exp functions and as such should have very small errors.
+
+[h4 Implementation]
+
+In the following table [mu] is the location parameter of the distribution,
+[sigma] is its scale parameter, /x/ is the random variate, /p/ is the probability
+and its complement /q = 1-p/.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Using the relation: pdf = e[super -abs(x-[mu]) \/ [sigma]] \/ (2 * [sigma]) ]]
+[[cdf][Using the relations:
+
+x < [mu] : p = e[super (x-[mu])/[sigma] ] \/ [sigma]
+
+x >= [mu] : p = 1 - e[super ([mu]-x)/[sigma] ] \/ [sigma]
+]]
+[[cdf complement][Using the relation:
+
+-x < [mu] : q = e[super (-x-[mu])/[sigma] ] \/ [sigma]
+
+-x >= [mu] : q = 1 - e[super ([mu]+x)/[sigma] ] \/ [sigma]
+]]
+[[quantile][Using the relations:
+
+p < 0.5 : x = [mu] + [sigma] * log(2*p)
+
+p >= 0.5 : x = [mu] - [sigma] * log(2-2*p)
+]]
+[[quantile from the complement][Using the relation:
+
+q > 0.5: x = [mu] + [sigma]*log(2-2*q)
+
+q <=0.5: x = [mu] - [sigma]*log( 2*q )
+]]
+[[mean][[mu]]]
+[[variance][2 * [sigma][super 2] ]]
+[[mode][[mu]]]
+[[skewness][0]]
+[[kurtosis][6]]
+[[kurtosis excess][3]]
+]
+
+[h4 References]
+
+* [@http://mathworld.wolfram.com/LaplaceDistribution.html Weisstein, Eric W. "Laplace Distribution."] From MathWorld--A Wolfram Web Resource.
+
+* [@http://en.wikipedia.org/wiki/Laplace_distribution Laplace Distribution]
+
+* M. Abramowitz and I. A. Stegun, Handbook of Mathematical Functions, 1972, p. 930.
+
+[endsect][/section:laplace_dist laplace]
+
+[/
+ Copyright 2008, 2009 John Maddock, Paul A. Bristow and M.A. (Thijs) van den Berg.
+ 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).
+]
+
diff --git a/doc/distributions/logistic.qbk b/doc/distributions/logistic.qbk
new file mode 100644
index 0000000..c2d04a8
--- /dev/null
+++ b/doc/distributions/logistic.qbk
@@ -0,0 +1,103 @@
+[section:logistic_dist Logistic Distribution]
+
+``#include <boost/math/distributions/logistic.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class logistic_distribution;
+
+ template <class RealType, class Policy>
+ class logistic_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+ // Construct:
+ logistic_distribution(RealType location = 0, RealType scale = 1);
+ // Accessors:
+ RealType location()const; // location.
+ RealType scale()const; // scale.
+
+ };
+
+ typedef logistic_distribution<> logistic;
+
+ }} // namespaces
+
+The logistic distribution is a continous probability distribution.
+It has two parameters - location and scale. The cumulative distribution
+function of the logistic distribution appears in logistic regression
+and feedforward neural networks. Among other applications,
+United State Chess Federation and FIDE use it to calculate chess ratings.
+
+The following graph shows how the distribution changes as the
+parameters change:
+
+[graph logistic_pdf]
+
+[h4 Member Functions]
+
+ logistic_distribution(RealType u = 0, RealType s = 1);
+
+Constructs a logistic distribution with location /u/ and scale /s/.
+
+Requires `scale > 0`, otherwise a __domain_error is raised.
+
+ RealType location()const;
+
+Returns the location of this distribution.
+
+ RealType scale()const;
+
+Returns the scale of this distribution.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
+that are generic to all distributions are supported: __usual_accessors.
+
+The domain of the random variable is \[-\[max_value\], +\[min_value\]\].
+However, the pdf and cdf support inputs of +[infin] and -[infin]
+as special cases if RealType permits.
+
+At `p=1` and `p=0`, the quantile function returns the result of
++__overflow_error and -__overflow_error, while the complement
+quantile function returns the result of -__overflow_error and
++__overflow_error respectively.
+
+[h4 Accuracy]
+
+The logistic distribution is implemented in terms of the `std::exp`
+and the `std::log` functions, so its accuracy is related to the
+accurate implementations of those functions on a given platform.
+When calculating the quantile with a non-zero /position/ parameter
+catastrophic cancellation errors can occur:
+in such cases, only a low /absolute error/ can be guaranteed.
+
+[h4 Implementation]
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Using the relation: pdf = e[super -(x-u)/s] / (s*(1+e[super -(x-u)/s])[super 2])]]
+[[cdf][Using the relation: p = 1/(1+e[super -(x-u)/s])]]
+[[cdf complement][Using the relation: q = 1/(1+e[super (x-u)/s])]]
+[[quantile][Using the relation: x = u - s*log(1/p-1)]]
+[[quantile from the complement][Using the relation: x = u + s*log(p/1-p)]]
+[[mean][u]]
+[[mode][The same as the mean.]]
+[[skewness][0]]
+[[kurtosis excess][6/5]]
+[[variance][ ([pi]*s)[super 2] / 3]]
+]
+
+[endsect]
+
+[/ logistic.qbk
+ Copyright 2006, 2007 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).
+]
+
diff --git a/doc/distributions/lognormal.qbk b/doc/distributions/lognormal.qbk
new file mode 100644
index 0000000..5f19ed5
--- /dev/null
+++ b/doc/distributions/lognormal.qbk
@@ -0,0 +1,119 @@
+[section:lognormal_dist Log Normal Distribution]
+
+``#include <boost/math/distributions/lognormal.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class lognormal_distribution;
+
+ typedef lognormal_distribution<> lognormal;
+
+ template <class RealType, class ``__Policy``>
+ class lognormal_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+ // Construct:
+ lognormal_distribution(RealType location = 0, RealType scale = 1);
+ // Accessors:
+ RealType location()const;
+ RealType scale()const;
+ };
+
+ }} // namespaces
+
+The lognormal distribution is the distribution that arises
+when the logarithm of the random variable is normally distributed.
+A lognormal distribution results when the variable is the product
+of a large number of independent, identically-distributed variables.
+
+For location and scale parameters /m/ and /s/ it is defined by the
+probability density function:
+
+[equation lognormal_ref]
+
+The location and scale parameters are equivalent to the mean and
+standard deviation of the logarithm of the random variable.
+
+The following graph illustrates the effect of the location
+parameter on the PDF, note that the range of the random
+variable remains \[0,+[infin]\] irrespective of the value of the
+location parameter:
+
+[graph lognormal_pdf1]
+
+The next graph illustrates the effect of the scale parameter on the PDF:
+
+[graph lognormal_pdf2]
+
+[h4 Member Functions]
+
+ lognormal_distribution(RealType location = 0, RealType scale = 1);
+
+Constructs a lognormal distribution with location /location/ and
+scale /scale/.
+
+The location parameter is the same as the mean of the logarithm of the
+random variate.
+
+The scale parameter is the same as the standard deviation of the
+logarithm of the random variate.
+
+Requires that the scale parameter is greater than zero, otherwise calls
+__domain_error.
+
+ RealType location()const;
+
+Returns the /location/ parameter of this distribution.
+
+ RealType scale()const;
+
+Returns the /scale/ parameter of this distribution.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] that are generic to all
+distributions are supported: __usual_accessors.
+
+The domain of the random variable is \[0,+[infin]\].
+
+[h4 Accuracy]
+
+The lognormal distribution is implemented in terms of the
+standard library log and exp functions, plus the
+[link math_toolkit.sf_erf.error_function error function],
+and as such should have very low error rates.
+
+[h4 Implementation]
+
+In the following table /m/ is the location parameter of the distribution,
+/s/ is its scale parameter, /x/ is the random variate, /p/ is the probability
+and /q = 1-p/.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Using the relation: pdf = e[super -(ln(x) - m)[super 2 ] \/ 2s[super 2 ] ] \/ (x * s * sqrt(2pi)) ]]
+[[cdf][Using the relation: p = cdf(normal_distribtion<RealType>(m, s), log(x)) ]]
+[[cdf complement][Using the relation: q = cdf(complement(normal_distribtion<RealType>(m, s), log(x))) ]]
+[[quantile][Using the relation: x = exp(quantile(normal_distribtion<RealType>(m, s), p))]]
+[[quantile from the complement][Using the relation: x = exp(quantile(complement(normal_distribtion<RealType>(m, s), q)))]]
+[[mean][e[super m + s[super 2 ] / 2 ] ]]
+[[variance][(e[super s[super 2] ] - 1) * e[super 2m + s[super 2 ] ] ]]
+[[mode][e[super m - s[super 2 ] ] ]]
+[[skewness][sqrt(e[super s[super 2] ] - 1) * (2 + e[super s[super 2] ]) ]]
+[[kurtosis][e[super 4s[super 2] ] + 2e[super 3s[super 2] ] + 3e[super 2s[super 2] ] - 3]]
+[[kurtosis excess][e[super 4s[super 2] ] + 2e[super 3s[super 2] ] + 3e[super 2s[super 2] ] - 6 ]]
+]
+
+[endsect][/section:normal_dist Normal]
+
+[/
+ 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).
+]
+
diff --git a/doc/distributions/nag_library.qbk b/doc/distributions/nag_library.qbk
new file mode 100644
index 0000000..4f728a1
--- /dev/null
+++ b/doc/distributions/nag_library.qbk
@@ -0,0 +1,60 @@
+[section:nag_library Comparison with C, R, FORTRAN-style Free Functions]
+
+You are probably familiar with a statistics library that has free functions,
+for example the classic [@http://nag.com/numeric/CL/CLdescription.asp NAG C library]
+and matching [@http://nag.com/numeric/FL/FLdescription.asp NAG FORTRAN Library],
+[@http://office.microsoft.com/en-us/excel/HP052090051033.aspx Microsoft Excel BINOMDIST(number_s,trials,probability_s,cumulative)],
+[@http://www.r-project.org/ R], [@http://www.ptc.com/products/mathcad/mathcad14/mathcad_func_chart.htm MathCAD pbinom]
+and many others.
+
+If so, you may find 'Distributions as Objects' unfamiliar, if not alien.
+
+However, *do not panic*, both definition and usage are not really very different.
+
+A very simple example of generating the same values as the
+[@http://nag.com/numeric/CL/CLdescription.asp NAG C library]
+for the binomial distribution follows.
+(If you find slightly different values, the Boost C++ version, using double or better,
+is very likely to be the more accurate.
+Of course, accuracy is not usually a concern for most applications of this function).
+
+The [@http://www.nag.co.uk/numeric/cl/manual/pdf/G01/g01bjc.pdf NAG function specification] is
+
+ void nag_binomial_dist(Integer n, double p, Integer k,
+ double *plek, double *pgtk, double *peqk, NagError *fail)
+
+and is called
+
+ g01bjc(n, p, k, &plek, &pgtk, &peqk, NAGERR_DEFAULT);
+
+The equivalent using this Boost C++ library is:
+
+ using namespace boost::math; // Using declaration avoids very long names.
+ binomial my_dist(4, 0.5); // c.f. NAG n = 4, p = 0.5
+
+and values can be output thus:
+
+ cout
+ << my_dist.trials() << " " // Echo the NAG input n = 4 trials.
+ << my_dist.success_fraction() << " " // Echo the NAG input p = 0.5
+ << cdf(my_dist, 2) << " " // NAG plek with k = 2
+ << cdf(complement(my_dist, 2)) << " " // NAG pgtk with k = 2
+ << pdf(my_dist, 2) << endl; // NAG peqk with k = 2
+
+`cdf(dist, k)` is equivalent to NAG library `plek`, lower tail probability of <= k
+
+`cdf(complement(dist, k))` is equivalent to NAG library `pgtk`, upper tail probability of > k
+
+`pdf(dist, k)` is equivalent to NAG library `peqk`, point probability of == k
+
+See [@../../example/binomial_example_nag.cpp binomial_example_nag.cpp] for details.
+
+[endsect] [/section:nag_library Comparison with C, R, FORTRAN-style Free Functions]
+
+[/
+ 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).
+]
+
diff --git a/doc/distributions/nc_beta.qbk b/doc/distributions/nc_beta.qbk
new file mode 100644
index 0000000..d74b716
--- /dev/null
+++ b/doc/distributions/nc_beta.qbk
@@ -0,0 +1,204 @@
+[section:nc_beta_dist Noncentral Beta Distribution]
+
+``#include <boost/math/distributions/non_central_beta.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class non_central_beta_distribution;
+
+ typedef non_central_beta_distribution<> non_central_beta;
+
+ template <class RealType, class ``__Policy``>
+ class non_central_beta_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ // Constructor:
+ non_central_beta_distribution(RealType alpha, RealType beta, RealType lambda);
+
+ // Accessor to shape parameters:
+ RealType alpha()const;
+ RealType beta()const;
+
+ // Accessor to non-centrality parameter lambda:
+ RealType non_centrality()const;
+ };
+
+ }} // namespaces
+
+The noncentral beta distribution is a generalization of the __beta_distrib.
+
+It is defined as the ratio
+X = [chi][sub m][super 2]([lambda]) \/ ([chi][sub m][super 2]([lambda])
++ [chi][sub n][super 2])
+where [chi][sub m][super 2]([lambda]) is a noncentral [chi][super 2]
+random variable with /m/ degrees of freedom, and [chi][sub n][super 2]
+is a central [chi][super 2] random variable with /n/ degrees of freedom.
+
+This gives a PDF that can be expressed as a Poisson mixture
+of beta distribution PDFs:
+
+[equation nc_beta_ref1]
+
+where P(i;[lambda]\/2) is the discrete Poisson probablity at /i/, with mean
+[lambda]\/2, and I[sub x][super ']([alpha], [beta]) is the derivative of
+the incomplete beta function. This leads to the usual form of the CDF
+as:
+
+[equation nc_beta_ref2]
+
+The following graph illustrates how the distribution changes
+for different values of [lambda]:
+
+[graph nc_beta_pdf]
+
+[h4 Member Functions]
+
+ non_central_beta_distribution(RealType a, RealType b, RealType lambda);
+
+Constructs a noncentral beta distribution with shape parameters /a/ and /b/
+and non-centrality parameter /lambda/.
+
+Requires a > 0, b > 0 and lambda >= 0, otherwise calls __domain_error.
+
+ RealType alpha()const;
+
+Returns the parameter /a/ from which this object was constructed.
+
+ RealType beta()const;
+
+Returns the parameter /b/ from which this object was constructed.
+
+ RealType non_centrality()const;
+
+Returns the parameter /lambda/ from which this object was constructed.
+
+[h4 Non-member Accessors]
+
+Most of the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
+are supported: __cdf, __pdf, __quantile, __mean, __variance, __sd,
+__median, __mode, __hazard, __chf, __range and __support.
+
+Mean and variance are implemented using hypergeometric pfq functions and relations given in
+[@http://reference.wolfram.com/mathematica/ref/NoncentralBetaDistribution.html Wolfram Noncentral Beta Distribution].
+
+However, the following are not currently implemented:
+ __skewness, __kurtosis and __kurtosis_excess.
+
+The domain of the random variable is \[0, 1\].
+
+[h4 Accuracy]
+
+The following table shows the peak errors
+(in units of [@http://en.wikipedia.org/wiki/Machine_epsilon epsilon])
+found on various platforms with various floating point types.
+The failures in the comparison to the [@http://www.r-project.org/ R Math library],
+seem to be mostly in the corner cases when the probablity would be very small.
+Unless otherwise specified any floating-point type that is narrower
+than the one shown will have __zero_error.
+
+[table_non_central_beta_CDF]
+
+[table_non_central_beta_CDF_complement]
+
+Error rates for the PDF, the complement of the CDF and for the quantile
+functions are broadly similar.
+
+[h4 Tests]
+
+There are two sets of test data used to verify this implementation:
+firstly we can compare with a few sample values generated by the
+[@http://www.r-project.org/ R library].
+Secondly, we have tables of test data, computed with this
+implementation and using interval arithmetic - this data should
+be accurate to at least 50 decimal digits - and is the used for
+our accuracy tests.
+
+[h4 Implementation]
+
+The CDF and its complement are evaluated as follows:
+
+First we determine which of the two values (the CDF or its
+complement) is likely to be the smaller, the crossover point
+is taken to be the mean of the distribution: for this we use the
+approximation due to: R. Chattamvelli and R. Shanmugam,
+"Algorithm AS 310: Computing the Non-Central Beta Distribution Function",
+Applied Statistics, Vol. 46, No. 1. (1997), pp. 146-156.
+
+[equation nc_beta_ref3]
+
+Then either the CDF or its complement is computed using the
+relations:
+
+[equation nc_beta_ref4]
+
+The summation is performed by starting at i = [lambda]/2, and then recursing
+in both directions, using the usual recurrence relations for the Poisson
+PDF and incomplete beta functions. This is the "Method 2" described
+by:
+
+Denise Benton and K. Krishnamoorthy,
+"Computing discrete mixtures of continuous
+distributions: noncentral chisquare, noncentral t
+and the distribution of the square of the sample
+multiple correlation coefficient",
+Computational Statistics & Data Analysis 43 (2003) 249-267.
+
+Specific applications of the above formulae to the noncentral
+beta distribution can be found in:
+
+Russell V. Lenth,
+"Algorithm AS 226: Computing Noncentral Beta Probabilities",
+Applied Statistics, Vol. 36, No. 2. (1987), pp. 241-244.
+
+H. Frick,
+"Algorithm AS R84: A Remark on Algorithm AS 226: Computing Non-Central Beta
+Probabilities", Applied Statistics, Vol. 39, No. 2. (1990), pp. 311-312.
+
+Ming Long Lam,
+"Remark AS R95: A Remark on Algorithm AS 226: Computing Non-Central Beta
+Probabilities", Applied Statistics, Vol. 44, No. 4. (1995), pp. 551-552.
+
+Harry O. Posten,
+"An Effective Algorithm for the Noncentral Beta Distribution Function",
+The American Statistician, Vol. 47, No. 2. (May, 1993), pp. 129-131.
+
+R. Chattamvelli,
+"A Note on the Noncentral Beta Distribution Function",
+The American Statistician, Vol. 49, No. 2. (May, 1995), pp. 231-234.
+
+Of these, the Posten reference provides the most complete overview,
+and includes the modification starting iteration at [lambda]/2.
+
+The main difference between this implementation and the above
+references is the direct computation of the complement when most
+efficient to do so, and the accumulation of the sum to -1 rather
+than subtracting the result from 1 at the end: this can substantially
+reduce the number of iterations required when the result is near 1.
+
+The PDF is computed using the methodology of Benton and Krishnamoorthy
+and the relation:
+
+[equation nc_beta_ref1]
+
+Quantiles are computed using a specially modified version of
+__bracket_solve,
+starting the search for the root at the mean of the distribution.
+(A Cornish-Fisher type expansion was also tried, but while this gets
+quite close to the root in many cases, when it is wrong it tends to
+introduce quite pathological behaviour: more investigation in this
+area is probably warranted).
+
+[endsect] [/section:nc_beta_dist]
+
+[/ nc_beta.qbk
+ Copyright 2008 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).
+]
+
diff --git a/doc/distributions/nc_chi_squared.qbk b/doc/distributions/nc_chi_squared.qbk
new file mode 100644
index 0000000..a1c2a32
--- /dev/null
+++ b/doc/distributions/nc_chi_squared.qbk
@@ -0,0 +1,273 @@
+[section:nc_chi_squared_dist Noncentral Chi-Squared Distribution]
+
+``#include <boost/math/distributions/non_central_chi_squared.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class non_central_chi_squared_distribution;
+
+ typedef non_central_chi_squared_distribution<> non_central_chi_squared;
+
+ template <class RealType, class ``__Policy``>
+ class non_central_chi_squared_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ // Constructor:
+ non_central_chi_squared_distribution(RealType v, RealType lambda);
+
+ // Accessor to degrees of freedom parameter v:
+ RealType degrees_of_freedom()const;
+
+ // Accessor to non centrality parameter lambda:
+ RealType non_centrality()const;
+
+ // Parameter finders:
+ static RealType find_degrees_of_freedom(RealType lambda, RealType x, RealType p);
+ template <class A, class B, class C>
+ static RealType find_degrees_of_freedom(const complemented3_type<A,B,C>& c);
+
+ static RealType find_non_centrality(RealType v, RealType x, RealType p);
+ template <class A, class B, class C>
+ static RealType find_non_centrality(const complemented3_type<A,B,C>& c);
+ };
+
+ }} // namespaces
+
+The noncentral chi-squared distribution is a generalization of the
+__chi_squared_distrib. If X[sub i] are [nu] independent, normally
+distributed random variables with means [mu][sub i] and variances
+[sigma][sub i][super 2], then the random variable
+
+[equation nc_chi_squ_ref1]
+
+is distributed according to the noncentral chi-squared distribution.
+
+The noncentral chi-squared distribution has two parameters:
+[nu] which specifies the number of degrees of freedom
+(i.e. the number of X[sub i]), and [lambda] which is related to the
+mean of the random variables X[sub i] by:
+
+[equation nc_chi_squ_ref2]
+
+(Note that some references define [lambda] as one half of the above sum).
+
+This leads to a PDF of:
+
+[equation nc_chi_squ_ref3]
+
+where ['f(x;k)] is the central chi-squared distribution PDF, and
+['I[sub v](x)] is a modified Bessel function of the first kind.
+
+The following graph illustrates how the distribution changes
+for different values of [lambda]:
+
+[graph nccs_pdf]
+
+[h4 Member Functions]
+
+ non_central_chi_squared_distribution(RealType v, RealType lambda);
+
+Constructs a Chi-Squared distribution with /v/ degrees of freedom
+and non-centrality parameter /lambda/.
+
+Requires v > 0 and lambda >= 0, otherwise calls __domain_error.
+
+ RealType degrees_of_freedom()const;
+
+Returns the parameter /v/ from which this object was constructed.
+
+ RealType non_centrality()const;
+
+Returns the parameter /lambda/ from which this object was constructed.
+
+
+ static RealType find_degrees_of_freedom(RealType lambda, RealType x, RealType p);
+
+This function returns the number of degrees of freedom /v/ such that:
+`cdf(non_central_chi_squared<RealType, Policy>(v, lambda), x) == p`
+
+ template <class A, class B, class C>
+ static RealType find_degrees_of_freedom(const complemented3_type<A,B,C>& c);
+
+When called with argument `boost::math::complement(lambda, x, q)`
+this function returns the number of degrees of freedom /v/ such that:
+
+`cdf(complement(non_central_chi_squared<RealType, Policy>(v, lambda), x)) == q`.
+
+ static RealType find_non_centrality(RealType v, RealType x, RealType p);
+
+This function returns the non centrality parameter /lambda/ such that:
+
+`cdf(non_central_chi_squared<RealType, Policy>(v, lambda), x) == p`
+
+ template <class A, class B, class C>
+ static RealType find_non_centrality(const complemented3_type<A,B,C>& c);
+
+When called with argument `boost::math::complement(v, x, q)`
+this function returns the non centrality parameter /lambda/ such that:
+
+`cdf(complement(non_central_chi_squared<RealType, Policy>(v, lambda), x)) == q`.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
+that are generic to all distributions are supported: __usual_accessors.
+
+The domain of the random variable is \[0, +[infin]\].
+
+[h4 Examples]
+
+There is a
+[link math_toolkit.stat_tut.weg.nccs_eg worked example]
+for the noncentral chi-squared distribution.
+
+[h4 Accuracy]
+
+The following table shows the peak errors
+(in units of [@http://en.wikipedia.org/wiki/Machine_epsilon epsilon])
+found on various platforms with various floating point types.
+The failures in the comparison to the [@http://www.r-project.org/ R Math library],
+seem to be mostly in the corner cases when the probablity would be very small.
+Unless otherwise specified any floating-point type that is narrower
+than the one shown will have __zero_error.
+
+[table_non_central_chi_squared_CDF]
+
+[table_non_central_chi_squared_CDF_complement]
+
+Error rates for the quantile
+functions are broadly similar. Special mention should go to
+the `mode` function: there is no closed form for this function,
+so it is evaluated numerically by finding the maxima of the PDF:
+in principal this can not produce an accuracy greater than the
+square root of the machine epsilon.
+
+[h4 Tests]
+
+There are two sets of test data used to verify this implementation:
+firstly we can compare with published data, for example with
+Table 6 of "Self-Validating Computations of Probabilities for
+Selected Central and Noncentral Univariate Probability Functions",
+Morgan C. Wang and William J. Kennedy,
+Journal of the American Statistical Association,
+Vol. 89, No. 427. (Sep., 1994), pp. 878-887.
+Secondly, we have tables of test data, computed with this
+implementation and using interval arithmetic - this data should
+be accurate to at least 50 decimal digits - and is the used for
+our accuracy tests.
+
+[h4 Implementation]
+
+The CDF and its complement are evaluated as follows:
+
+First we determine which of the two values (the CDF or its
+complement) is likely to be the smaller: for this we can use the
+relation due to Temme (see "Asymptotic and Numerical Aspects of the
+Noncentral Chi-Square Distribution", N. M. Temme, Computers Math. Applic.
+Vol 25, No. 5, 55-63, 1993) that:
+
+F([nu],[lambda];[nu]+[lambda]) [asymp] 0.5
+
+and so compute the CDF when the random variable is less than
+[nu]+[lambda], and its complement when the random variable is
+greater than [nu]+[lambda]. If necessary the computed result
+is then subtracted from 1 to give the desired result (the CDF or its
+complement).
+
+For small values of the non centrality parameter, the CDF is computed
+using the method of Ding (see "Algorithm AS 275: Computing the Non-Central
+#2 Distribution Function", Cherng G. Ding, Applied Statistics, Vol. 41,
+No. 2. (1992), pp. 478-482). This uses the following series representation:
+
+[equation nc_chi_squ_ref4]
+
+which requires just one call to __gamma_p_derivative with the subsequent
+terms being computed by recursion as shown above.
+
+For larger values of the non-centrality parameter, Ding's method can take
+an unreasonable number of terms before convergence is achieved. Furthermore,
+the largest term is not the first term, so in extreme cases the first term may
+be zero, leading to a zero result, even though the true value may be non-zero.
+
+Therefore, when the non-centrality parameter is greater than 200, the method due
+to Krishnamoorthy (see "Computing discrete mixtures of continuous distributions:
+noncentral chisquare, noncentral t and the distribution of the
+square of the sample multiple correlation coefficient",
+Denise Benton and K. Krishnamoorthy, Computational Statistics &
+Data Analysis, 43, (2003), 249-267) is used.
+
+This method uses the well known sum:
+
+[equation nc_chi_squ_ref5]
+
+Where P[sub a](x) is the incomplete gamma function.
+
+The method starts at the [lambda]th term, which is where the Poisson weighting
+function achieves its maximum value, although this is not necessarily
+the largest overall term. Subsequent terms are calculated via the normal
+recurrence relations for the incomplete gamma function, and iteration proceeds
+both forwards and backwards until sufficient precision has been achieved. It
+should be noted that recurrence in the forwards direction of P[sub a](x) is
+numerically unstable. However, since we always start /after/ the largest
+term in the series, numeric instability is introduced more slowly than the
+series converges.
+
+Computation of the complement of the CDF uses an extension of Krishnamoorthy's
+method, given that:
+
+[equation nc_chi_squ_ref6]
+
+we can again start at the [lambda]'th term and proceed in both directions from
+there until the required precision is achieved. This time it is backwards
+recursion on the incomplete gamma function Q[sub a](x) which is unstable.
+However, as long as we start well /before/ the largest term, this is not an
+issue in practice.
+
+The PDF is computed directly using the relation:
+
+[equation nc_chi_squ_ref3]
+
+Where ['f(x; v)] is the PDF of the central __chi_squared_distrib and
+['I[sub v](x)] is a modified Bessel function, see __cyl_bessel_i.
+For small values of the
+non-centrality parameter the relation in terms of __cyl_bessel_i
+is used. However, this method fails for large values of the
+non-centrality parameter, so in that case the infinite sum is
+evaluated using the method of Benton and Krishnamoorthy, and
+the usual recurrence relations for successive terms.
+
+The quantile functions are computed by numeric inversion of the CDF.
+An improve starting quess is from
+Thomas Luu,
+[@http://discovery.ucl.ac.uk/1482128/, Fast and accurate parallel computation of quantile functions for random number generation, Doctorial Thesis, 2016].
+
+There is no [@http://en.wikipedia.org/wiki/Closed_form closed form]
+for the mode of the noncentral chi-squared
+distribution: it is computed numerically by finding the maximum
+of the PDF. Likewise, the median is computed numerically via
+the quantile.
+
+The remaining non-member functions use the following formulas:
+
+[equation nc_chi_squ_ref7]
+
+Some analytic properties of noncentral distributions
+(particularly unimodality, and monotonicity of their modes)
+are surveyed and summarized by:
+
+Andrea van Aubel & Wolfgang Gawronski, Applied Mathematics and Computation, 141 (2003) 3-12.
+
+[endsect] [/section:nc_chi_squared_dist]
+
+[/ nc_chi_squared.qbk
+ Copyright 2008 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).
+]
+
diff --git a/doc/distributions/nc_chi_squared_example.qbk b/doc/distributions/nc_chi_squared_example.qbk
new file mode 100644
index 0000000..38f45b0
--- /dev/null
+++ b/doc/distributions/nc_chi_squared_example.qbk
@@ -0,0 +1,20 @@
+[section:nccs_eg Non Central Chi Squared Example]
+
+(See also the reference documentation for the __non_central_chi_squared_distrib.)
+
+[section:nccs_power_eg Tables of the power function of the chi[super 2] test.]
+[/chi super 2 failed to show the chi in pdf why??? (OK in html) so use words.]
+
+[import ../../example/nc_chi_sq_example.cpp]
+[nccs_eg]
+
+[endsect] [/nccs_power_eg Tables of the power function of the chi-squared [chi][super 2] test.]
+
+[endsect] [/section:nccs_eg Non Central Chi Squared Example]
+
+[/
+ Copyright 2006, 2011 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).
+]
diff --git a/doc/distributions/nc_f.qbk b/doc/distributions/nc_f.qbk
new file mode 100644
index 0000000..535a5da
--- /dev/null
+++ b/doc/distributions/nc_f.qbk
@@ -0,0 +1,193 @@
+[section:nc_f_dist Noncentral F Distribution]
+
+``#include <boost/math/distributions/non_central_f.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class non_central_f_distribution;
+
+ typedef non_central_f_distribution<> non_central_f;
+
+ template <class RealType, class ``__Policy``>
+ class non_central_f_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ // Constructor:
+ non_central_f_distribution(RealType v1, RealType v2, RealType lambda);
+
+ // Accessor to degrees_of_freedom parameters v1 & v2:
+ RealType degrees_of_freedom1()const;
+ RealType degrees_of_freedom2()const;
+
+ // Accessor to non-centrality parameter lambda:
+ RealType non_centrality()const;
+ };
+
+ }} // namespaces
+
+The noncentral F distribution is a generalization of the __F_distrib.
+It is defined as the ratio
+
+ F = (X/v1) / (Y/v2)
+
+where X is a noncentral [chi][super 2]
+random variable with /v1/ degrees of freedom and non-centrality parameter [lambda],
+and Y is a central [chi][super 2] random variable with /v2/ degrees of freedom.
+
+This gives the following PDF:
+
+[equation nc_f_ref1]
+
+where L[sub a][super b](c) is a generalised Laguerre polynomial and B(a,b) is the
+__beta function, or
+
+[equation nc_f_ref2]
+
+The following graph illustrates how the distribution changes
+for different values of [lambda]:
+
+[graph nc_f_pdf]
+
+[h4 Member Functions]
+
+ non_central_f_distribution(RealType v1, RealType v2, RealType lambda);
+
+Constructs a non-central beta distribution with parameters /v1/ and /v2/
+and non-centrality parameter /lambda/.
+
+Requires v1 > 0, v2 > 0 and lambda >= 0, otherwise calls __domain_error.
+
+ RealType degrees_of_freedom1()const;
+
+Returns the parameter /v1/ from which this object was constructed.
+
+ RealType degrees_of_freedom2()const;
+
+Returns the parameter /v2/ from which this object was constructed.
+
+ RealType non_centrality()const;
+
+Returns the non-centrality parameter /lambda/ from which this object was constructed.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
+that are generic to all distributions are supported: __usual_accessors.
+
+The domain of the random variable is \[0, +[infin]\].
+
+[h4 Accuracy]
+
+This distribution is implemented in terms of the
+__non_central_beta_distrib: refer to that distribution for accuracy data.
+
+[h4 Tests]
+
+Since this distribution is implemented by adapting another distribution,
+the tests consist of basic sanity checks computed by the
+[@http://www.r-project.org/ R-2.5.1 Math library statistical
+package] and its pbeta and dbeta functions.
+
+[h4 Implementation]
+
+In the following table /v1/ and /v2/ are the first and second
+degrees of freedom parameters of the distribution, [lambda]
+is the non-centrality parameter,
+/x/ is the random variate, /p/ is the probability, and /q = 1-p/.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Implemented in terms of the non-central beta PDF using the relation:
+
+f(x;v1,v2;[lambda]) = (v1\/v2) / ((1+y)*(1+y)) * g(y\/(1+y);v1\/2,v2\/2;[lambda])
+
+where g(x; a, b; [lambda]) is the non central beta PDF, and:
+
+y = x * v1 \/ v2
+]]
+[[cdf][Using the relation:
+
+p = B[sub y](v1\/2, v2\/2; [lambda])
+
+where B[sub x](a, b; [lambda]) is the noncentral beta distribution CDF and
+
+y = x * v1 \/ v2
+
+]]
+
+[[cdf complement][Using the relation:
+
+q = 1 - B[sub y](v1\/2, v2\/2; [lambda])
+
+where 1 - B[sub x](a, b; [lambda]) is the complement of the
+noncentral beta distribution CDF and
+
+y = x * v1 \/ v2
+
+]]
+[[quantile][Using the relation:
+
+x = (bx \/ (1-bx)) * (v1 \/ v2)
+
+where
+
+bx = Q[sub p][super -1](v1\/2, v2\/2; [lambda])
+
+and
+
+Q[sub p][super -1](v1\/2, v2\/2; [lambda])
+
+is the noncentral beta quantile.
+
+]]
+[[quantile
+
+from the complement][
+Using the relation:
+
+x = (bx \/ (1-bx)) * (v1 \/ v2)
+
+where
+
+bx = QC[sub q][super -1](v1\/2, v2\/2; [lambda])
+
+and
+
+QC[sub q][super -1](v1\/2, v2\/2; [lambda])
+
+is the noncentral beta quantile from the complement.]]
+[[mean][v2 * (v1 + l) \/ (v1 * (v2 - 2))]]
+[[mode][By numeric maximalisation of the PDF.]]
+[[variance][Refer to, [@http://mathworld.wolfram.com/NoncentralF-Distribution.html
+ Weisstein, Eric W. "Noncentral F-Distribution." From MathWorld--A Wolfram Web Resource.] ]]
+[[skewness][Refer to, [@http://mathworld.wolfram.com/NoncentralF-Distribution.html
+ Weisstein, Eric W. "Noncentral F-Distribution." From MathWorld--A Wolfram Web Resource.],
+ and to the [@http://reference.wolfram.com/mathematica/ref/NoncentralFRatioDistribution.html
+ Mathematica documentation] ]]
+[[kurtosis and kurtosis excess]
+ [Refer to, [@http://mathworld.wolfram.com/NoncentralF-Distribution.html
+ Weisstein, Eric W. "Noncentral F-Distribution." From MathWorld--A Wolfram Web Resource.],
+ and to the [@http://reference.wolfram.com/mathematica/ref/NoncentralFRatioDistribution.html
+ Mathematica documentation] ]]
+]
+
+Some analytic properties of noncentral distributions
+(particularly unimodality, and monotonicity of their modes)
+are surveyed and summarized by:
+
+Andrea van Aubel & Wolfgang Gawronski, Applied Mathematics and Computation, 141 (2003) 3-12.
+
+[endsect] [/section:nc_f_dist]
+
+[/ nc_f.qbk
+ Copyright 2008 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).
+]
+
diff --git a/doc/distributions/nc_t.qbk b/doc/distributions/nc_t.qbk
new file mode 100644
index 0000000..5318d1a
--- /dev/null
+++ b/doc/distributions/nc_t.qbk
@@ -0,0 +1,224 @@
+[section:nc_t_dist Noncentral T Distribution]
+
+``#include <boost/math/distributions/non_central_t.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class non_central_t_distribution;
+
+ typedef non_central_t_distribution<> non_central_t;
+
+ template <class RealType, class ``__Policy``>
+ class non_central_t_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ // Constructor:
+ non_central_t_distribution(RealType v, RealType delta);
+
+ // Accessor to degrees_of_freedom parameter v:
+ RealType degrees_of_freedom()const;
+
+ // Accessor to non-centrality parameter delta:
+ RealType non_centrality()const;
+ };
+
+ }} // namespaces
+
+The noncentral T distribution is a generalization of the __students_t_distrib.
+Let X have a normal distribution with mean [delta] and variance 1, and let
+[nu] S[super 2] have
+a chi-squared distribution with degrees of freedom [nu]. Assume that
+X and S[super 2] are independent. The
+distribution of t[sub [nu]]([delta])=X/S is called a
+noncentral t distribution with degrees of freedom [nu] and noncentrality
+parameter [delta].
+
+This gives the following PDF:
+
+[equation nc_t_ref1]
+
+where [sub 1]F[sub 1](a;b;x) is a confluent hypergeometric function.
+
+The following graph illustrates how the distribution changes
+for different values of [nu] and [delta]:
+
+[graph nc_t_pdf]
+[graph nc_t_cdf]
+
+[h4 Member Functions]
+
+ non_central_t_distribution(RealType v, RealType delta);
+
+Constructs a non-central t distribution with degrees of freedom
+parameter /v/ and non-centrality parameter /delta/.
+
+Requires /v/ > 0 (including positive infinity) and finite /delta/, otherwise calls __domain_error.
+
+ RealType degrees_of_freedom()const;
+
+Returns the parameter /v/ from which this object was constructed.
+
+ RealType non_centrality()const;
+
+Returns the non-centrality parameter /delta/ from which this object was constructed.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
+that are generic to all distributions are supported: __usual_accessors.
+
+The domain of the random variable is \[-[infin], +[infin]\].
+
+[h4 Accuracy]
+
+The following table shows the peak errors
+(in units of [@http://en.wikipedia.org/wiki/Machine_epsilon epsilon])
+found on various platforms with various floating-point types.
+Unless otherwise specified, any floating-point type that is narrower
+than the one shown will have __zero_error.
+
+[table_non_central_t_CDF]
+
+[table_non_central_t_CDF_complement]
+
+[caution The complexity of the current algorithm is dependent upon
+[delta][super 2]: consequently the time taken to evaluate the CDF
+increases rapidly for [delta] > 500, likewise the accuracy decreases
+rapidly for very large [delta].]
+
+Accuracy for the quantile and PDF functions should be broadly similar.
+The /mode/ is determined numerically and cannot
+in principal be more accurate than the square root of
+floating-point type FPT epsilon, accessed using `boost::math::tools::epsilon<FPT>()`.
+For 64-bit `double`, epsilon is about 1e-16, so the fractional accuracy is limited to 1e-8.
+
+[h4 Tests]
+
+There are two sets of tests of this distribution:
+
+Basic sanity checks compare this implementation to the test values given in
+"Computing discrete mixtures of continuous
+distributions: noncentral chisquare, noncentral t
+and the distribution of the square of the sample
+multiple correlation coefficient."
+Denise Benton, K. Krishnamoorthy,
+Computational Statistics & Data Analysis 43 (2003) 249-267.
+
+Accuracy checks use test data computed with this
+implementation and arbitary precision interval arithmetic:
+this test data is believed to be accurate to at least 50
+decimal places.
+
+The cases of large (or infinite) [nu] and/or large [delta] has received special
+treatment to avoid catastrophic loss of accuracy.
+New tests have been added to confirm the improvement achieved.
+
+From Boost 1.52, degrees of freedom [nu] can be +[infin]
+when the normal distribution located at [delta]
+(equivalent to the central Student's t distribution)
+is used in place for accuracy and speed.
+
+[h4 Implementation]
+
+The CDF is computed using a modification of the method
+described in
+"Computing discrete mixtures of continuous
+distributions: noncentral chisquare, noncentral t
+and the distribution of the square of the sample
+multiple correlation coefficient."
+Denise Benton, K. Krishnamoorthy,
+Computational Statistics & Data Analysis 43 (2003) 249-267.
+
+This uses the following formula for the CDF:
+
+[equation nc_t_ref2]
+
+Where I[sub x](a,b) is the incomplete beta function, and
+[Phi](x) is the normal CDF at x.
+
+Iteration starts at the largest of the Poisson weighting terms
+(at i = [delta][super 2] / 2) and then proceeds in both directions
+as per Benton and Krishnamoorthy's paper.
+
+Alternatively, by considering what happens when t = [infin], we have
+x = 1, and therefore I[sub x](a,b) = 1 and:
+
+[equation nc_t_ref3]
+
+From this we can easily show that:
+
+[equation nc_t_ref4]
+
+and therefore we have a means to compute either the probability or its
+complement directly without the risk of cancellation error. The
+crossover criterion for choosing whether to calculate the CDF or
+its complement is the same as for the
+__non_central_beta_distrib.
+
+The PDF can be computed by a very similar method using:
+
+[equation nc_t_ref5]
+
+Where I[sub x][super '](a,b) is the derivative of the incomplete beta function.
+
+For both the PDF and CDF we switch to approximating the distribution by a
+Student's t distribution centred on [delta] when [nu] is very large.
+The crossover location appears to be when [delta]/(4[nu]) < [epsilon],
+this location was estimated by inspection of equation 2.6 in
+"A Comparison of Approximations To Percentiles of the
+Noncentral t-Distribution". H. Sahai and M. M. Ojeda,
+Revista Investigacion Operacional Vol 21, No 2, 2000, page 123.
+
+Equation 2.6 is a Fisher-Cornish expansion by Eeden and Johnson.
+The second term includes the ratio [delta]/(4[nu]),
+so when this term become negligible, this and following terms can be ignored,
+leaving just Student's t distribution centred on [delta].
+
+This was also confirmed by experimental testing.
+
+See also
+
+* "Some Approximations to the Percentage Points of the Noncentral
+t-Distribution". C. van Eeden. International Statistical Review, 29, 4-31.
+
+* "Continuous Univariate Distributions". N.L. Johnson, S. Kotz and
+N. Balkrishnan. 1995. John Wiley and Sons New York.
+
+The quantile is calculated via the usual
+__root_finding_without_derivatives method
+with the initial guess taken as the quantile of a normal approximation
+to the noncentral T.
+
+There is no closed form for the mode, so this is computed via
+functional maximisation of the PDF.
+
+The remaining functions (mean, variance etc) are implemented
+using the formulas given in
+Weisstein, Eric W. "Noncentral Student's t-Distribution."
+From MathWorld--A Wolfram Web Resource.
+[@http://mathworld.wolfram.com/NoncentralStudentst-Distribution.html
+http://mathworld.wolfram.com/NoncentralStudentst-Distribution.html]
+and in the
+[@http://reference.wolfram.com/mathematica/ref/NoncentralStudentTDistribution.html
+Mathematica documentation].
+
+Some analytic properties of noncentral distributions
+(particularly unimodality, and monotonicity of their modes)
+are surveyed and summarized by:
+
+Andrea van Aubel & Wolfgang Gawronski, Applied Mathematics and Computation, 141 (2003) 3-12.
+
+[endsect] [/section:nc_t_dist]
+
+[/ nc_t.qbk
+ Copyright 2008, 2012 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).
+]
+
diff --git a/doc/distributions/negative_binomial.qbk b/doc/distributions/negative_binomial.qbk
new file mode 100644
index 0000000..0c5a4be
--- /dev/null
+++ b/doc/distributions/negative_binomial.qbk
@@ -0,0 +1,373 @@
+[section:negative_binomial_dist Negative Binomial Distribution]
+
+``#include <boost/math/distributions/negative_binomial.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class negative_binomial_distribution;
+
+ typedef negative_binomial_distribution<> negative_binomial;
+
+ template <class RealType, class ``__Policy``>
+ class negative_binomial_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+ // Constructor from successes and success_fraction:
+ negative_binomial_distribution(RealType r, RealType p);
+
+ // Parameter accessors:
+ RealType success_fraction() const;
+ RealType successes() const;
+
+ // Bounds on success fraction:
+ static RealType find_lower_bound_on_p(
+ RealType trials,
+ RealType successes,
+ RealType probability); // alpha
+ static RealType find_upper_bound_on_p(
+ RealType trials,
+ RealType successes,
+ RealType probability); // alpha
+
+ // Estimate min/max number of trials:
+ static RealType find_minimum_number_of_trials(
+ RealType k, // Number of failures.
+ RealType p, // Success fraction.
+ RealType probability); // Probability threshold alpha.
+ static RealType find_maximum_number_of_trials(
+ RealType k, // Number of failures.
+ RealType p, // Success fraction.
+ RealType probability); // Probability threshold alpha.
+ };
+
+ }} // namespaces
+
+The class type `negative_binomial_distribution` represents a
+[@http://en.wikipedia.org/wiki/Negative_binomial_distribution negative_binomial distribution]:
+it is used when there are exactly two mutually exclusive outcomes of a
+[@http://en.wikipedia.org/wiki/Bernoulli_trial Bernoulli trial]:
+these outcomes are labelled "success" and "failure".
+
+For k + r Bernoulli trials each with success fraction p, the
+negative_binomial distribution gives the probability of observing
+k failures and r successes with success on the last trial.
+The negative_binomial distribution
+assumes that success_fraction p is fixed for all (k + r) trials.
+
+[note The random variable for the negative binomial distribution is the number of trials,
+(the number of successes is a fixed property of the distribution)
+whereas for the binomial,
+the random variable is the number of successes, for a fixed number of trials.]
+
+It has the PDF:
+
+[equation neg_binomial_ref]
+
+The following graph illustrate how the PDF varies as the success fraction
+/p/ changes:
+
+[graph negative_binomial_pdf_1]
+
+Alternatively, this graph shows how the shape of the PDF varies as
+the number of successes changes:
+
+[graph negative_binomial_pdf_2]
+
+[h4 Related Distributions]
+
+The name negative binomial distribution is reserved by some to the
+case where the successes parameter r is an integer.
+This integer version is also called the
+[@http://mathworld.wolfram.com/PascalDistribution.html Pascal distribution].
+
+This implementation uses real numbers for the computation throughout
+(because it uses the *real-valued* incomplete beta function family of functions).
+This real-valued version is also called the Polya Distribution.
+
+The Poisson distribution is a generalization of the Pascal distribution,
+where the success parameter r is an integer: to obtain the Pascal
+distribution you must ensure that an integer value is provided for r,
+and take integer values (floor or ceiling) from functions that return
+a number of successes.
+
+For large values of r (successes), the negative binomial distribution
+converges to the Poisson distribution.
+
+The geometric distribution is a special case
+where the successes parameter r = 1,
+so only a first and only success is required.
+geometric(p) = negative_binomial(1, p).
+
+The Poisson distribution is a special case for large successes
+
+poisson([lambda]) = lim [sub r [rarr] [infin]] [space] negative_binomial(r, r / ([lambda] + r)))
+
+[discrete_quantile_warning Negative Binomial]
+
+[h4 Member Functions]
+
+[h5 Construct]
+
+ negative_binomial_distribution(RealType r, RealType p);
+
+Constructor: /r/ is the total number of successes, /p/ is the
+probability of success of a single trial.
+
+Requires: `r > 0` and `0 <= p <= 1`.
+
+[h5 Accessors]
+
+ RealType success_fraction() const; // successes / trials (0 <= p <= 1)
+
+Returns the parameter /p/ from which this distribution was constructed.
+
+ RealType successes() const; // required successes (r > 0)
+
+Returns the parameter /r/ from which this distribution was constructed.
+
+The best method of calculation for the following functions is disputed:
+see __binomial_distrib for more discussion.
+
+[h5 Lower Bound on Parameter p]
+
+ static RealType find_lower_bound_on_p(
+ RealType failures,
+ RealType successes,
+ RealType probability) // (0 <= alpha <= 1), 0.05 equivalent to 95% confidence.
+
+Returns a *lower bound* on the success fraction:
+
+[variablelist
+[[failures][The total number of failures before the ['r]th success.]]
+[[successes][The number of successes required.]]
+[[alpha][The largest acceptable probability that the true value of
+ the success fraction is [*less than] the value returned.]]
+]
+
+For example, if you observe /k/ failures and /r/ successes from /n/ = k + r trials
+the best estimate for the success fraction is simply ['r/n], but if you
+want to be 95% sure that the true value is [*greater than] some value,
+['p[sub min]], then:
+
+ p``[sub min]`` = negative_binomial_distribution<RealType>::find_lower_bound_on_p(
+ failures, successes, 0.05);
+
+[link math_toolkit.stat_tut.weg.neg_binom_eg.neg_binom_conf See negative binomial confidence interval example.]
+
+This function uses the Clopper-Pearson method of computing the lower bound on the
+success fraction, whilst many texts refer to this method as giving an "exact"
+result in practice it produces an interval that guarantees ['at least] the
+coverage required, and may produce pessimistic estimates for some combinations
+of /failures/ and /successes/. See:
+
+[@http://www.ucs.louisiana.edu/~kxk4695/Discrete_new.pdf
+Yong Cai and K. Krishnamoorthy, A Simple Improved Inferential Method for Some Discrete Distributions.
+Computational statistics and data analysis, 2005, vol. 48, no3, 605-621].
+
+[h5 Upper Bound on Parameter p]
+
+ static RealType find_upper_bound_on_p(
+ RealType trials,
+ RealType successes,
+ RealType alpha); // (0 <= alpha <= 1), 0.05 equivalent to 95% confidence.
+
+Returns an *upper bound* on the success fraction:
+
+[variablelist
+[[trials][The total number of trials conducted.]]
+[[successes][The number of successes that occurred.]]
+[[alpha][The largest acceptable probability that the true value of
+ the success fraction is [*greater than] the value returned.]]
+]
+
+For example, if you observe /k/ successes from /n/ trials the
+best estimate for the success fraction is simply ['k/n], but if you
+want to be 95% sure that the true value is [*less than] some value,
+['p[sub max]], then:
+
+ p``[sub max]`` = negative_binomial_distribution<RealType>::find_upper_bound_on_p(
+ r, k, 0.05);
+
+[link math_toolkit.stat_tut.weg.neg_binom_eg.neg_binom_conf See negative binomial confidence interval example.]
+
+This function uses the Clopper-Pearson method of computing the lower bound on the
+success fraction, whilst many texts refer to this method as giving an "exact"
+result in practice it produces an interval that guarantees ['at least] the
+coverage required, and may produce pessimistic estimates for some combinations
+of /failures/ and /successes/. See:
+
+[@http://www.ucs.louisiana.edu/~kxk4695/Discrete_new.pdf
+Yong Cai and K. Krishnamoorthy, A Simple Improved Inferential Method for Some Discrete Distributions.
+Computational statistics and data analysis, 2005, vol. 48, no3, 605-621].
+
+[h5 Estimating Number of Trials to Ensure at Least a Certain Number of Failures]
+
+ static RealType find_minimum_number_of_trials(
+ RealType k, // number of failures.
+ RealType p, // success fraction.
+ RealType alpha); // probability threshold (0.05 equivalent to 95%).
+
+This functions estimates the number of trials required to achieve a certain
+probability that [*more than k failures will be observed].
+
+[variablelist
+[[k][The target number of failures to be observed.]]
+[[p][The probability of ['success] for each trial.]]
+[[alpha][The maximum acceptable risk that only k failures or fewer will be observed.]]
+]
+
+For example:
+
+ negative_binomial_distribution<RealType>::find_minimum_number_of_trials(10, 0.5, 0.05);
+
+Returns the smallest number of trials we must conduct to be 95% sure
+of seeing 10 failures that occur with frequency one half.
+
+[link math_toolkit.stat_tut.weg.neg_binom_eg.neg_binom_size_eg Worked Example.]
+
+This function uses numeric inversion of the negative binomial distribution
+to obtain the result: another interpretation of the result, is that it finds
+the number of trials (success+failures) that will lead to an /alpha/ probability
+of observing k failures or fewer.
+
+[h5 Estimating Number of Trials to Ensure a Maximum Number of Failures or Less]
+
+ static RealType find_maximum_number_of_trials(
+ RealType k, // number of failures.
+ RealType p, // success fraction.
+ RealType alpha); // probability threshold (0.05 equivalent to 95%).
+
+This functions estimates the maximum number of trials we can conduct and achieve
+a certain probability that [*k failures or fewer will be observed].
+
+[variablelist
+[[k][The maximum number of failures to be observed.]]
+[[p][The probability of ['success] for each trial.]]
+[[alpha][The maximum acceptable ['risk] that more than k failures will be observed.]]
+]
+
+For example:
+
+ negative_binomial_distribution<RealType>::find_maximum_number_of_trials(0, 1.0-1.0/1000000, 0.05);
+
+Returns the largest number of trials we can conduct and still be 95% sure
+of seeing no failures that occur with frequency one in one million.
+
+This function uses numeric inversion of the negative binomial distribution
+to obtain the result: another interpretation of the result, is that it finds
+the number of trials (success+failures) that will lead to an /alpha/ probability
+of observing more than k failures.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
+that are generic to all distributions are supported: __usual_accessors.
+
+However it's worth taking a moment to define what these actually mean in
+the context of this distribution:
+
+[table Meaning of the non-member accessors.
+[[Function][Meaning]]
+[[__pdf]
+ [The probability of obtaining [*exactly k failures] from k+r trials
+ with success fraction p. For example:
+
+``pdf(negative_binomial(r, p), k)``]]
+[[__cdf]
+ [The probability of obtaining [*k failures or fewer] from k+r trials
+ with success fraction p and success on the last trial. For example:
+
+``cdf(negative_binomial(r, p), k)``]]
+[[__ccdf]
+ [The probability of obtaining [*more than k failures] from k+r trials
+ with success fraction p and success on the last trial. For example:
+
+``cdf(complement(negative_binomial(r, p), k))``]]
+[[__quantile]
+ [The [*greatest] number of failures k expected to be observed from k+r trials
+ with success fraction p, at probability P. Note that the value returned
+ is a real-number, and not an integer. Depending on the use case you may
+ want to take either the floor or ceiling of the real result. For example:
+
+``quantile(negative_binomial(r, p), P)``]]
+[[__quantile_c]
+ [The [*smallest] number of failures k expected to be observed from k+r trials
+ with success fraction p, at probability P. Note that the value returned
+ is a real-number, and not an integer. Depending on the use case you may
+ want to take either the floor or ceiling of the real result. For example:
+ ``quantile(complement(negative_binomial(r, p), P))``]]
+]
+
+[h4 Accuracy]
+
+This distribution is implemented using the
+incomplete beta functions __ibeta and __ibetac:
+please refer to these functions for information on accuracy.
+
+[h4 Implementation]
+
+In the following table, /p/ is the probability that any one trial will
+be successful (the success fraction), /r/ is the number of successes,
+/k/ is the number of failures, /p/ is the probability and /q = 1-p/.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][pdf = exp(lgamma(r + k) - lgamma(r) - lgamma(k+1)) * pow(p, r) * pow((1-p), k)
+
+Implementation is in terms of __ibeta_derivative:
+
+(p/(r + k)) * ibeta_derivative(r, static_cast<RealType>(k+1), p)
+The function __ibeta_derivative is used here, since it has already
+been optimised for the lowest possible error - indeed this is really
+just a thin wrapper around part of the internals of the incomplete
+beta function.
+]]
+[[cdf][Using the relation:
+
+cdf = I[sub p](r, k+1) = ibeta(r, k+1, p)
+
+= ibeta(r, static_cast<RealType>(k+1), p)]]
+[[cdf complement][Using the relation:
+
+1 - cdf = I[sub p](k+1, r)
+
+= ibetac(r, static_cast<RealType>(k+1), p)
+]]
+[[quantile][ibeta_invb(r, p, P) - 1]]
+[[quantile from the complement][ibetac_invb(r, p, Q) -1)]]
+[[mean][ `r(1-p)/p` ]]
+[[variance][ `r (1-p) / p * p` ]]
+[[mode][`floor((r-1) * (1 - p)/p)`]]
+[[skewness][`(2 - p) / sqrt(r * (1 - p))`]]
+[[kurtosis][`6 / r + (p * p) / r * (1 - p )`]]
+[[kurtosis excess][`6 / r + (p * p) / r * (1 - p ) -3`]]
+[[parameter estimation member functions][]]
+[[`find_lower_bound_on_p`][ibeta_inv(successes, failures + 1, alpha)]]
+[[`find_upper_bound_on_p`][ibetac_inv(successes, failures, alpha) plus see comments in code.]]
+[[`find_minimum_number_of_trials`][ibeta_inva(k + 1, p, alpha)]]
+[[`find_maximum_number_of_trials`][ibetac_inva(k + 1, p, alpha)]]
+]
+
+Implementation notes:
+
+* The real concept type (that deliberately lacks the Lanczos approximation),
+was found to take several minutes to evaluate some extreme test values,
+so the test has been disabled for this type.
+
+* Much greater speed, and perhaps greater accuracy,
+might be achieved for extreme values by using a normal approximation.
+This is NOT been tested or implemented.
+
+[endsect][/section:negative_binomial_dist Negative Binomial]
+
+[/ negative_binomial.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).
+]
+
diff --git a/doc/distributions/negative_binomial_example.qbk b/doc/distributions/negative_binomial_example.qbk
new file mode 100644
index 0000000..4c992bd
--- /dev/null
+++ b/doc/distributions/negative_binomial_example.qbk
@@ -0,0 +1,192 @@
+[section:neg_binom_eg Negative Binomial Distribution Examples]
+
+(See also the reference documentation for the __negative_binomial_distrib.)
+
+[section:neg_binom_conf Calculating Confidence Limits on the Frequency of Occurrence for the Negative Binomial Distribution]
+
+Imagine you have a process that follows a negative binomial distribution:
+for each trial conducted, an event either occurs or does it does not, referred
+to as "successes" and "failures". The frequency with which successes occur
+is variously referred to as the
+success fraction, success ratio, success percentage, occurrence frequency, or probability of occurrence.
+
+If, by experiment, you want to measure the
+ the best estimate of success fraction is given simply
+by /k/ \/ /N/, for /k/ successes out of /N/ trials.
+
+However our confidence in that estimate will be shaped by how many trials were conducted,
+and how many successes were observed. The static member functions
+`negative_binomial_distribution<>::find_lower_bound_on_p` and
+`negative_binomial_distribution<>::find_upper_bound_on_p`
+allow you to calculate the confidence intervals for your estimate of the success fraction.
+
+The sample program [@../../example/neg_binom_confidence_limits.cpp
+neg_binom_confidence_limits.cpp] illustrates their use.
+
+[import ../../example/neg_binom_confidence_limits.cpp]
+
+[neg_binomial_confidence_limits]
+Let's see some sample output for a 1 in 10
+success ratio, first for a mere 20 trials:
+
+[pre'''______________________________________________
+2-Sided Confidence Limits For Success Fraction
+______________________________________________
+Number of trials = 20
+Number of successes = 2
+Number of failures = 18
+Observed frequency of occurrence = 0.1
+___________________________________________
+Confidence Lower Upper
+ Value (%) Limit Limit
+___________________________________________
+ 50.000 0.04812 0.13554
+ 75.000 0.03078 0.17727
+ 90.000 0.01807 0.22637
+ 95.000 0.01235 0.26028
+ 99.000 0.00530 0.33111
+ 99.900 0.00164 0.41802
+ 99.990 0.00051 0.49202
+ 99.999 0.00016 0.55574
+''']
+
+As you can see, even at the 95% confidence level the bounds (0.012 to 0.26) are
+really very wide, and very asymmetric about the observed value 0.1.
+
+Compare that with the program output for a mass
+2000 trials:
+
+[pre'''______________________________________________
+2-Sided Confidence Limits For Success Fraction
+______________________________________________
+Number of trials = 2000
+Number of successes = 200
+Number of failures = 1800
+Observed frequency of occurrence = 0.1
+___________________________________________
+Confidence Lower Upper
+ Value (%) Limit Limit
+___________________________________________
+ 50.000 0.09536 0.10445
+ 75.000 0.09228 0.10776
+ 90.000 0.08916 0.11125
+ 95.000 0.08720 0.11352
+ 99.000 0.08344 0.11802
+ 99.900 0.07921 0.12336
+ 99.990 0.07577 0.12795
+ 99.999 0.07282 0.13206
+''']
+
+Now even when the confidence level is very high, the limits (at 99.999%, 0.07 to 0.13) are really
+quite close and nearly symmetric to the observed value of 0.1.
+
+[endsect][/section:neg_binom_conf Calculating Confidence Limits on the Frequency of Occurrence]
+
+[section:neg_binom_size_eg Estimating Sample Sizes for the Negative Binomial.]
+
+Imagine you have an event
+(let's call it a "failure" - though we could equally well call it a success if we felt it was a 'good' event)
+that you know will occur in 1 in N trials. You may want to know how many trials you need to
+conduct to be P% sure of observing at least k such failures.
+If the failure events follow a negative binomial
+distribution (each trial either succeeds or fails)
+then the static member function `negative_binomial_distibution<>::find_minimum_number_of_trials`
+can be used to estimate the minimum number of trials required to be P% sure
+of observing the desired number of failures.
+
+The example program
+[@../../example/neg_binomial_sample_sizes.cpp neg_binomial_sample_sizes.cpp]
+demonstrates its usage.
+
+[import ../../example/neg_binomial_sample_sizes.cpp]
+[neg_binomial_sample_sizes]
+
+[note Since we're calculating the /minimum/ number of trials required,
+we'll err on the safe side and take the ceiling of the result.
+Had we been calculating the
+/maximum/ number of trials permitted to observe less than a certain
+number of /failures/ then we would have taken the floor instead. We
+would also have called `find_minimum_number_of_trials` like this:
+``
+ floor(negative_binomial::find_minimum_number_of_trials(failures, p, alpha[i]))
+``
+which would give us the largest number of trials we could conduct and
+still be P% sure of observing /failures or less/ failure events, when the
+probability of success is /p/.]
+
+We'll finish off by looking at some sample output, firstly suppose
+we wish to observe at least 5 "failures" with a 50/50 (0.5) chance of
+success or failure:
+
+[pre
+'''Target number of failures = 5, Success fraction = 50%
+
+____________________________
+Confidence Min Number
+ Value (%) Of Trials
+____________________________
+ 50.000 11
+ 75.000 14
+ 90.000 17
+ 95.000 18
+ 99.000 22
+ 99.900 27
+ 99.990 31
+ 99.999 36
+'''
+]
+
+So 18 trials or more would yield a 95% chance that at least our 5
+required failures would be observed.
+
+Compare that to what happens if the success ratio is 90%:
+
+[pre'''Target number of failures = 5.000, Success fraction = 90.000%
+
+____________________________
+Confidence Min Number
+ Value (%) Of Trials
+____________________________
+ 50.000 57
+ 75.000 73
+ 90.000 91
+ 95.000 103
+ 99.000 127
+ 99.900 159
+ 99.990 189
+ 99.999 217
+''']
+
+So now 103 trials are required to observe at least 5 failures with
+95% certainty.
+
+[endsect] [/section:neg_binom_size_eg Estimating Sample Sizes.]
+
+[section:negative_binomial_example1 Negative Binomial Sales Quota Example.]
+
+This example program
+[@../../example/negative_binomial_example1.cpp negative_binomial_example1.cpp (full source code)]
+demonstrates a simple use to find the probability of meeting a sales quota.
+
+[import ../../example/negative_binomial_example1.cpp]
+[negative_binomial_eg1_1]
+[negative_binomial_eg1_2]
+
+[endsect] [/section:negative_binomial_example1]
+
+[section:negative_binomial_example2 Negative Binomial Table Printing Example.]
+Example program showing output of a table of values of cdf and pdf for various k failures.
+[import ../../example/negative_binomial_example2.cpp]
+[neg_binomial_example2]
+[neg_binomial_example2_1]
+[endsect] [/section:negative_binomial_example1 Negative Binomial example 2.]
+
+[endsect] [/section:neg_binom_eg Negative Binomial Distribution Examples]
+
+[/
+ 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).
+]
+
diff --git a/doc/distributions/non_members.qbk b/doc/distributions/non_members.qbk
new file mode 100644
index 0000000..653d249
--- /dev/null
+++ b/doc/distributions/non_members.qbk
@@ -0,0 +1,406 @@
+[section:nmp Non-Member Properties]
+
+Properties that are common to all distributions are accessed via non-member
+getter functions: non-membership allows more of these functions to be added over time,
+as the need arises. Unfortunately the literature uses many different and
+confusing names to refer to a rather small number of actual concepts; refer
+to the [link math_toolkit.dist_ref.nmp.concept_index concept index] to find the property you
+want by the name you are most familiar with.
+Or use the [link math_toolkit.dist_ref.nmp.function_index function index]
+to go straight to the function you want if you already know its name.
+
+[h4:function_index Function Index]
+
+* __cdf.
+* __ccdf.
+* __chf.
+* __hazard.
+* __kurtosis.
+* __kurtosis_excess
+* __mean.
+* __median.
+* __mode.
+* __pdf.
+* __range.
+* __quantile.
+* __quantile_c.
+* __skewness.
+* __sd.
+* __support.
+* __variance.
+
+[h4:concept_index Conceptual Index]
+
+* __ccdf.
+* __cdf.
+* __chf.
+* [link math_toolkit.dist_ref.nmp.cdf_inv Inverse Cumulative Distribution Function].
+* [link math_toolkit.dist_ref.nmp.survival_inv Inverse Survival Function].
+* __hazard
+* [link math_toolkit.dist_ref.nmp.lower_critical Lower Critical Value].
+* __kurtosis.
+* __kurtosis_excess
+* __mean.
+* __median.
+* __mode.
+* [link math_toolkit.dist_ref.nmp.cdfPQ P].
+* [link math_toolkit.dist_ref.nmp.percent Percent Point Function].
+* __pdf.
+* [link math_toolkit.dist_ref.nmp.pmf Probability Mass Function].
+* __range.
+* [link math_toolkit.dist_ref.nmp.cdfPQ Q].
+* __quantile.
+* [link math_toolkit.dist_ref.nmp.quantile_c Quantile from the complement of the probability].
+* __skewness.
+* __sd
+* [link math_toolkit.dist_ref.nmp.survival Survival Function].
+* [link math_toolkit.dist_ref.nmp.support support].
+* [link math_toolkit.dist_ref.nmp.upper_critical Upper Critical Value].
+* __variance.
+
+[h4:cdf Cumulative Distribution Function]
+
+ template <class RealType, class ``__Policy``>
+ RealType cdf(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist, const RealType& x);
+
+The __cdf is the probability that
+the variable takes a value less than or equal to x. It is equivalent
+to the integral from -infinity to x of the __pdf.
+
+This function may return a __domain_error if the random variable is outside
+the defined range for the distribution.
+
+For example, the following graph shows the cdf for the
+normal distribution:
+
+[$../graphs/cdf.png]
+
+[h4:ccdf Complement of the Cumulative Distribution Function]
+
+ template <class Distribution, class RealType>
+ RealType cdf(const ``['Unspecified-Complement-Type]``<Distribution, RealType>& comp);
+
+The complement of the __cdf
+is the probability that
+the variable takes a value greater than x. It is equivalent
+to the integral from x to infinity of the __pdf, or 1 minus the __cdf of x.
+
+This is also known as the survival function.
+
+This function may return a __domain_error if the random variable is outside
+the defined range for the distribution.
+
+In this library, it is obtained by wrapping the arguments to the `cdf`
+function in a call to `complement`, for example:
+
+ // standard normal distribution object:
+ boost::math::normal norm;
+ // print survival function for x=2.0:
+ std::cout << cdf(complement(norm, 2.0)) << std::endl;
+
+For example, the following graph shows the __complement of the cdf for the
+normal distribution:
+
+[$../graphs/survival.png]
+
+See __why_complements for why the complement is useful and when it should be used.
+
+[h4:hazard Hazard Function]
+
+ template <class RealType, class ``__Policy``>
+ RealType hazard(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist, const RealType& x);
+
+Returns the __hazard of /x/ and distibution /dist/.
+
+This function may return a __domain_error if the random variable is outside
+the defined range for the distribution.
+
+[equation hazard]
+
+[caution
+Some authors refer to this as the conditional failure
+density function rather than the hazard function.]
+
+[h4:chf Cumulative Hazard Function]
+
+ template <class RealType, class ``__Policy``>
+ RealType chf(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist, const RealType& x);
+
+Returns the __chf of /x/ and distibution /dist/.
+
+This function may return a __domain_error if the random variable is outside
+the defined range for the distribution.
+
+[equation chf]
+
+[caution
+Some authors refer to this as simply the "Hazard Function".]
+
+[h4:mean mean]
+
+ template<class RealType, class ``__Policy``>
+ RealType mean(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
+
+Returns the mean of the distribution /dist/.
+
+This function may return a __domain_error if the distribution does not have
+a defined mean (for example the Cauchy distribution).
+
+[h4:median median]
+
+ template<class RealType, class ``__Policy``>
+ RealType median(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
+
+Returns the median of the distribution /dist/.
+
+[h4:mode mode]
+
+ template<class RealType, ``__Policy``>
+ RealType mode(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
+
+Returns the mode of the distribution /dist/.
+
+This function may return a __domain_error if the distribution does not have
+a defined mode.
+
+[h4:pdf Probability Density Function]
+
+ template <class RealType, class ``__Policy``>
+ RealType pdf(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist, const RealType& x);
+
+For a continuous function, the probability density function (pdf) returns
+the probability that the variate has the value x.
+Since for continuous distributions the probability at a single point is actually zero,
+the probability is better expressed as the integral of the pdf between two points:
+see the __cdf.
+
+For a discrete distribution, the pdf is the probability that the
+variate takes the value x.
+
+This function may return a __domain_error if the random variable is outside
+the defined range for the distribution.
+
+For example, for a standard normal distribution the pdf looks like this:
+
+[$../graphs/pdf.png]
+
+[h4:range Range]
+
+ template<class RealType, class ``__Policy``>
+ std::pair<RealType, RealType> range(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
+
+Returns the valid range of the random variable over distribution /dist/.
+
+[h4:quantile Quantile]
+
+ template <class RealType, class ``__Policy``>
+ RealType quantile(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist, const RealType& p);
+
+The quantile is best viewed as the inverse of the __cdf, it returns
+a value /x/ such that `cdf(dist, x) == p`.
+
+This is also known as the /percent point function/, or /percentile/, or /fractile/,
+it is also the same as calculating the ['lower critical value] of a distribution.
+
+This function returns a __domain_error if the probability lies outside [0,1].
+The function may return an __overflow_error if there is no finite value
+that has the specified probability.
+
+The following graph shows the quantile function for a standard normal
+distribution:
+
+[$../graphs/quantile.png]
+
+[h4:quantile_c Quantile from the complement of the probability.]
+See also [link math_toolkit.stat_tut.overview.complements complements].
+
+
+ template <class Distribution, class RealType>
+ RealType quantile(const ``['Unspecified-Complement-Type]``<Distribution, RealType>& comp);
+
+This is the inverse of the __ccdf. It is calculated by wrapping
+the arguments in a call to the quantile function in a call to
+/complement/. For example:
+
+ // define a standard normal distribution:
+ boost::math::normal norm;
+ // print the value of x for which the complement
+ // of the probability is 0.05:
+ std::cout << quantile(complement(norm, 0.05)) << std::endl;
+
+The function computes a value /x/ such that
+`cdf(complement(dist, x)) == q` where /q/ is complement of the
+probability.
+
+[link why_complements Why complements?]
+
+This function is also called the inverse survival function, and is the
+same as calculating the ['upper critical value] of a distribution.
+
+This function returns a __domain_error if the probablity lies outside [0,1].
+The function may return an __overflow_error if there is no finite value
+that has the specified probability.
+
+The following graph show the inverse survival function for the normal
+distribution:
+
+[$../graphs/survival_inv.png]
+
+[h4:sd Standard Deviation]
+
+ template <class RealType, class ``__Policy``>
+ RealType standard_deviation(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
+
+Returns the standard deviation of distribution /dist/.
+
+This function may return a __domain_error if the distribution does not have
+a defined standard deviation.
+
+[h4:support support]
+
+ template<class RealType, class ``__Policy``>
+ std::pair<RealType, RealType> support(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
+
+Returns the supported range of random variable over the distribution /dist/.
+
+The distribution 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"].
+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.
+
+[h4:variance Variance]
+
+ template <class RealType, class ``__Policy``>
+ RealType variance(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
+
+Returns the variance of the distribution /dist/.
+
+This function may return a __domain_error if the distribution does not have
+a defined variance.
+
+[h4:skewness Skewness]
+
+ template <class RealType, class ``__Policy``>
+ RealType skewness(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
+
+Returns the skewness of the distribution /dist/.
+
+This function may return a __domain_error if the distribution does not have
+a defined skewness.
+
+[h4:kurtosis Kurtosis]
+
+ template <class RealType, class ``__Policy``>
+ RealType kurtosis(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
+
+Returns the 'proper' kurtosis (normalized fourth moment) of the distribution /dist/.
+
+kertosis = [beta][sub 2][space]= [mu][sub 4][space] / [mu][sub 2][super 2]
+
+Where [mu][sub i][space] is the i'th central moment of the distribution, and
+in particular [mu][sub 2][space] is the variance of the distribution.
+
+The kurtosis is a measure of the "peakedness" of a distribution.
+
+Note that the literature definition of kurtosis is confusing.
+The definition used here is that used by for example
+[@http://mathworld.wolfram.com/Kurtosis.html Wolfram MathWorld]
+(that includes a table of formulae for kurtosis excess for various distributions)
+but NOT the definition of
+[@http://en.wikipedia.org/wiki/Kurtosis kurtosis used by Wikipedia]
+which treats "kurtosis" and "kurtosis excess" as the same quantity.
+
+ kurtosis_excess = 'proper' kurtosis - 3
+
+This subtraction of 3 is convenient so that the ['kurtosis excess]
+of a normal distribution is zero.
+
+This function may return a __domain_error if the distribution does not have
+a defined kurtosis.
+
+'Proper' kurtosis can have a value from zero to + infinity.
+
+[h4:kurtosis_excess Kurtosis excess]
+
+ template <class RealType, ``__Policy``>
+ RealType kurtosis_excess(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
+
+Returns the kurtosis excess of the distribution /dist/.
+
+kurtosis excess = [gamma][sub 2][space]= [mu][sub 4][space] / [mu][sub 2][super 2][space]- 3 = kurtosis - 3
+
+Where [mu][sub i][space] is the i'th central moment of the distribution, and
+in particular [mu][sub 2][space] is the variance of the distribution.
+
+The kurtosis excess is a measure of the "peakedness" of a distribution, and
+is more widely used than the "kurtosis proper". It is defined so that
+the kurtosis excess of a normal distribution is zero.
+
+This function may return a __domain_error if the distribution does not have
+a defined kurtosis excess.
+
+Kurtosis excess can have a value from -2 to + infinity.
+
+ kurtosis = kurtosis_excess +3;
+
+The kurtosis excess of a normal distribution is zero.
+
+[h4:cdfPQ P and Q]
+
+The terms P and Q are sometimes used to refer to the __cdf
+and its [link math_toolkit.dist_ref.nmp.ccdf complement] respectively.
+Lowercase p and q are sometimes used to refer to the values returned
+by these functions.
+
+[h4:percent Percent Point Function or Percentile]
+
+The percent point function, also known as the percentile, is the same as
+the __quantile.
+
+[h4:cdf_inv Inverse CDF Function.]
+
+The inverse of the cumulative distribution function, is the same as the
+__quantile.
+
+[h4:survival_inv Inverse Survival Function.]
+
+The inverse of the survival function, is the same as computing the
+[link math_toolkit.dist_ref.nmp.quantile_c quantile
+from the complement of the probability].
+
+[h4:pmf Probability Mass Function]
+
+The Probability Mass Function is the same as the __pdf.
+
+The term Mass Function is usually applied to discrete distributions,
+while the term __pdf applies to continuous distributions.
+
+[h4:lower_critical Lower Critical Value.]
+
+The lower critical value calculates the value of the random variable
+given the area under the left tail of the distribution.
+It is equivalent to calculating the __quantile.
+
+[h4: upper_critical Upper Critical Value.]
+
+The upper critical value calculates the value of the random variable
+given the area under the right tail of the distribution. It is equivalent to
+calculating the [link math_toolkit.dist_ref.nmp.quantile_c quantile from the complement of the
+probability].
+
+[h4:survival Survival Function]
+
+Refer to the __ccdf.
+
+[endsect][/section:nmp Non-Member Properties]
+
+
+[/ non_members.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).
+]
+
diff --git a/doc/distributions/normal.qbk b/doc/distributions/normal.qbk
new file mode 100644
index 0000000..a3db989
--- /dev/null
+++ b/doc/distributions/normal.qbk
@@ -0,0 +1,120 @@
+[section:normal_dist Normal (Gaussian) Distribution]
+
+``#include <boost/math/distributions/normal.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class normal_distribution;
+
+ typedef normal_distribution<> normal;
+
+ template <class RealType, class ``__Policy``>
+ class normal_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+ // Construct:
+ normal_distribution(RealType mean = 0, RealType sd = 1);
+ // Accessors:
+ RealType mean()const; // location.
+ RealType standard_deviation()const; // scale.
+ // Synonyms, provided to allow generic use of find_location and find_scale.
+ RealType location()const;
+ RealType scale()const;
+ };
+
+ }} // namespaces
+
+The normal distribution is probably the most well known statistical
+distribution: it is also known as the Gaussian Distribution.
+A normal distribution with mean zero and standard deviation one
+is known as the ['Standard Normal Distribution].
+
+Given mean [mu][space]and standard deviation [sigma][space]it has the PDF:
+
+[space] [equation normal_ref1]
+
+The variation the PDF with its parameters is illustrated
+in the following graph:
+
+[graph normal_pdf]
+
+The cumulative distribution function is given by
+
+[space] [equation normal_cdf]
+
+and illustrated by this graph
+
+[graph normal_cdf]
+
+
+[h4 Member Functions]
+
+ normal_distribution(RealType mean = 0, RealType sd = 1);
+
+Constructs a normal distribution with mean /mean/ and
+standard deviation /sd/.
+
+Requires sd > 0, otherwise __domain_error is called.
+
+ RealType mean()const;
+ RealType location()const;
+
+both return the /mean/ of this distribution.
+
+ RealType standard_deviation()const;
+ RealType scale()const;
+
+both return the /standard deviation/ of this distribution.
+(Redundant location and scale function are provided to match other similar distributions,
+allowing the functions find_location and find_scale to be used generically).
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] that are generic to all
+distributions are supported: __usual_accessors.
+
+The domain of the random variable is \[-[max_value], +[min_value]\].
+However, the pdf of +[infin] and -[infin] = 0 is also supported,
+and cdf at -[infin] = 0, cdf at +[infin] = 1,
+and complement cdf -[infin] = 1 and +[infin] = 0,
+if RealType permits.
+
+[h4 Accuracy]
+
+The normal distribution is implemented in terms of the
+[link math_toolkit.sf_erf.error_function error function],
+and as such should have very low error rates.
+
+[h4 Implementation]
+
+In the following table /m/ is the mean of the distribution,
+and /s/ is its standard deviation.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Using the relation: pdf = e[super -(x-m)[super 2]\/(2s[super 2])] \/ (s * sqrt(2*pi)) ]]
+[[cdf][Using the relation: p = 0.5 * __erfc(-(x-m)/(s*sqrt(2))) ]]
+[[cdf complement][Using the relation: q = 0.5 * __erfc((x-m)/(s*sqrt(2))) ]]
+[[quantile][Using the relation: x = m - s * sqrt(2) * __erfc_inv(2*p)]]
+[[quantile from the complement][Using the relation: x = m + s * sqrt(2) * __erfc_inv(2*p)]]
+[[mean and standard deviation][The same as `dist.mean()` and `dist.standard_deviation()`]]
+[[mode][The same as the mean.]]
+[[median][The same as the mean.]]
+[[skewness][0]]
+[[kurtosis][3]]
+[[kurtosis excess][0]]
+]
+
+[endsect] [/section:normal_dist Normal]
+
+[/ normal.qbk
+ Copyright 2006, 2007, 2012 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).
+]
+
diff --git a/doc/distributions/normal_example.qbk b/doc/distributions/normal_example.qbk
new file mode 100644
index 0000000..c8dc4a0
--- /dev/null
+++ b/doc/distributions/normal_example.qbk
@@ -0,0 +1,36 @@
+[section:normal_example Normal Distribution Examples]
+
+(See also the reference documentation for the __normal_distrib.)
+
+[section:normal_misc Some Miscellaneous Examples of the Normal (Gaussian) Distribution]
+
+The sample program [@../../example/normal_misc_examples.cpp
+normal_misc_examples.cpp] illustrates their use.
+
+[import ../../example/normal_misc_examples.cpp]
+
+[h4 Traditional Tables]
+[normal_basic1]
+
+[h4 Standard deviations either side of the Mean]
+[normal_basic2]
+[h4 Some simple examples]
+[h4 Life of light bulbs]
+[normal_bulbs_example1]
+[h4 How many onions?]
+[normal_bulbs_example3]
+[h4 Packing beef]
+[normal_bulbs_example4]
+[h4 Length of bolts]
+[normal_bulbs_example5]
+
+[endsect] [/section:normal_misc Some Miscellaneous Examples of the Normal Distribution]
+[endsect] [/section:normal_example Normal Distribution Examples]
+
+[/
+ 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).
+]
+
diff --git a/doc/distributions/pareto.qbk b/doc/distributions/pareto.qbk
new file mode 100644
index 0000000..7584d53
--- /dev/null
+++ b/doc/distributions/pareto.qbk
@@ -0,0 +1,121 @@
+[section:pareto Pareto Distribution]
+
+
+``#include <boost/math/distributions/pareto.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class pareto_distribution;
+
+ typedef pareto_distribution<> pareto;
+
+ template <class RealType, class ``__Policy``>
+ class pareto_distribution
+ {
+ public:
+ typedef RealType value_type;
+ // Constructor:
+ pareto_distribution(RealType scale = 1, RealType shape = 1)
+ // Accessors:
+ RealType scale()const;
+ RealType shape()const;
+ };
+
+ }} // namespaces
+
+The [@http://en.wikipedia.org/wiki/pareto_distribution Pareto distribution]
+is a continuous distribution with the
+[@http://en.wikipedia.org/wiki/Probability_density_function probability density function (pdf)]:
+
+f(x; [alpha], [beta]) = [alpha][beta][super [alpha]] / x[super [alpha]+ 1]
+
+For shape parameter [alpha][space] > 0, and scale parameter [beta][space] > 0.
+If x < [beta][space], the pdf is zero.
+
+The [@http://mathworld.wolfram.com/ParetoDistribution.html Pareto distribution]
+often describes the larger compared to the smaller.
+A classic example is that 80% of the wealth is owned by 20% of the population.
+
+The following graph illustrates how the PDF varies with the scale parameter [beta]:
+
+[graph pareto_pdf1]
+
+And this graph illustrates how the PDF varies with the shape parameter [alpha]:
+
+[graph pareto_pdf2]
+
+
+[h4 Related distributions]
+
+
+[h4 Member Functions]
+
+ pareto_distribution(RealType scale = 1, RealType shape = 1);
+
+Constructs a [@http://en.wikipedia.org/wiki/pareto_distribution
+pareto distribution] with shape /shape/ and scale /scale/.
+
+Requires that the /shape/ and /scale/ parameters are both greater than zero,
+otherwise calls __domain_error.
+
+ RealType scale()const;
+
+Returns the /scale/ parameter of this distribution.
+
+ RealType shape()const;
+
+Returns the /shape/ parameter of this distribution.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] that are generic to all
+distributions are supported: __usual_accessors.
+
+The supported domain of the random variable is \[scale, [infin]\].
+
+[h4 Accuracy]
+
+The Pareto distribution is implemented in terms of the
+standard library `exp` functions plus __expm1
+and so should have very small errors, usually only a few epsilon.
+
+If probability is near to unity (or the complement of a probability near zero) see also __why_complements.
+
+[h4 Implementation]
+
+In the following table [alpha][space] is the shape parameter of the distribution, and
+[beta][space] is its scale parameter, /x/ is the random variate, /p/ is the probability
+and its complement /q = 1-p/.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Using the relation: pdf p = [alpha][beta][super [alpha]]/x[super [alpha] +1] ]]
+[[cdf][Using the relation: cdf p = 1 - ([beta][space] / x)[super [alpha]] ]]
+[[cdf complement][Using the relation: q = 1 - p = -([beta][space] / x)[super [alpha]] ]]
+[[quantile][Using the relation: x = [beta] / (1 - p)[super 1/[alpha]] ]]
+[[quantile from the complement][Using the relation: x = [beta] / (q)[super 1/[alpha]] ]]
+[[mean][[alpha][beta] / ([beta] - 1) ]]
+[[variance][[beta][alpha][super 2] / ([beta] - 1)[super 2] ([beta] - 2) ]]
+[[mode][[alpha]]]
+[[skewness][Refer to [@http://mathworld.wolfram.com/ParetoDistribution.html Weisstein, Eric W. "Pareto Distribution." From MathWorld--A Wolfram Web Resource.] ]]
+[[kurtosis][Refer to [@http://mathworld.wolfram.com/ParetoDistribution.html Weisstein, Eric W. "Pareto Distribution." From MathWorld--A Wolfram Web Resource.] ]]
+[[kurtosis excess][Refer to [@http://mathworld.wolfram.com/ParetoDistribution.html Weisstein, Eric W. "pareto Distribution." From MathWorld--A Wolfram Web Resource.] ]]
+]
+
+[h4 References]
+* [@http://en.wikipedia.org/wiki/pareto_distribution Pareto Distribution]
+* [@http://mathworld.wolfram.com/paretoDistribution.html Weisstein, Eric W. "Pareto Distribution." From MathWorld--A Wolfram Web Resource.]
+* Handbook of Statistical Distributions with Applications, K Krishnamoorthy, ISBN 1-58488-635-8, Chapter 23, pp 257 - 267.
+(Note the meaning of a and b is reversed in Wolfram and Krishnamoorthy).
+
+[endsect][/section:pareto pareto]
+
+[/
+ Copyright 2006, 2009 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).
+]
+
diff --git a/doc/distributions/poisson.qbk b/doc/distributions/poisson.qbk
new file mode 100644
index 0000000..432862e
--- /dev/null
+++ b/doc/distributions/poisson.qbk
@@ -0,0 +1,103 @@
+[section:poisson_dist Poisson Distribution]
+
+``#include <boost/math/distributions/poisson.hpp>``
+
+ namespace boost { namespace math {
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class poisson_distribution;
+
+ typedef poisson_distribution<> poisson;
+
+ template <class RealType, class ``__Policy``>
+ class poisson_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ poisson_distribution(RealType mean = 1); // Constructor.
+ RealType mean()const; // Accessor.
+ }
+
+ }} // namespaces boost::math
+
+The [@http://en.wikipedia.org/wiki/Poisson_distribution Poisson distribution]
+is a well-known statistical discrete distribution.
+It expresses the probability of a number of events
+(or failures, arrivals, occurrences ...)
+occurring in a fixed period of time,
+provided these events occur with a known mean rate [lambda][space]
+(events/time), and are independent of the time since the last event.
+
+The distribution was discovered by Sim__eacute on-Denis Poisson (1781 to 1840).
+
+It has the Probability Mass Function:
+
+[equation poisson_ref1]
+
+for k events, with an expected number of events [lambda].
+
+The following graph illustrates how the PDF varies with the parameter [lambda]:
+
+[graph poisson_pdf_1]
+
+[discrete_quantile_warning Poisson]
+
+[h4 Member Functions]
+
+ poisson_distribution(RealType mean = 1);
+
+Constructs a poisson distribution with mean /mean/.
+
+ RealType mean()const;
+
+Returns the /mean/ of this distribution.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] that are generic to all
+distributions are supported: __usual_accessors.
+
+The domain of the random variable is \[0, [infin]\].
+
+[h4 Accuracy]
+
+The Poisson distribution is implemented in terms of the
+incomplete gamma functions __gamma_p and __gamma_q
+and as such should have low error rates: but refer to the documentation
+of those functions for more information.
+The quantile and its complement use the inverse gamma functions
+and are therefore probably slightly less accurate: this is because the
+inverse gamma functions are implemented using an iterative method with a
+lower tolerance to avoid excessive computation.
+
+[h4 Implementation]
+
+In the following table [lambda][space] is the mean of the distribution,
+/k/ is the random variable, /p/ is the probability and /q = 1-p/.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Using the relation: pdf = e[super -[lambda]] [lambda][super k] \/ k! ]]
+[[cdf][Using the relation: p = [Gamma](k+1, [lambda]) \/ k! = __gamma_q(k+1, [lambda])]]
+[[cdf complement][Using the relation: q = __gamma_p(k+1, [lambda]) ]]
+[[quantile][Using the relation: k = __gamma_q_inva([lambda], p) - 1]]
+[[quantile from the complement][Using the relation: k = __gamma_p_inva([lambda], q) - 1]]
+[[mean][[lambda]]]
+[[mode][ floor ([lambda]) or [floorlr[lambda]] ]]
+[[skewness][1/[radic][lambda]]]
+[[kurtosis][3 + 1/[lambda]]]
+[[kurtosis excess][1/[lambda]]]
+]
+
+[/ poisson.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).
+]
+
+[endsect][/section:poisson_dist Poisson]
+
diff --git a/doc/distributions/rayleigh.qbk b/doc/distributions/rayleigh.qbk
new file mode 100644
index 0000000..910c2b7
--- /dev/null
+++ b/doc/distributions/rayleigh.qbk
@@ -0,0 +1,119 @@
+[section:rayleigh Rayleigh Distribution]
+
+
+``#include <boost/math/distributions/rayleigh.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class rayleigh_distribution;
+
+ typedef rayleigh_distribution<> rayleigh;
+
+ template <class RealType, class ``__Policy``>
+ class rayleigh_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+ // Construct:
+ rayleigh_distribution(RealType sigma = 1)
+ // Accessors:
+ RealType sigma()const;
+ };
+
+ }} // namespaces
+
+The [@http://en.wikipedia.org/wiki/Rayleigh_distribution Rayleigh distribution]
+is a continuous distribution with the
+[@http://en.wikipedia.org/wiki/Probability_density_function probability density function]:
+
+f(x; sigma) = x * exp(-x[super 2]/2 [sigma][super 2]) / [sigma][super 2]
+
+For sigma parameter [sigma][space] > 0, and x > 0.
+
+The Rayleigh distribution is often used where two orthogonal components
+have an absolute value,
+for example, wind velocity and direction may be combined to yield a wind speed,
+or real and imaginary components may have absolute values that are Rayleigh distributed.
+
+The following graph illustrates how the Probability density Function(pdf) varies with the shape parameter [sigma]:
+
+[graph rayleigh_pdf]
+
+and the Cumulative Distribution Function (cdf)
+
+[graph rayleigh_cdf]
+
+[h4 Related distributions]
+
+The absolute value of two independent normal distributions X and Y, [radic] (X[super 2] + Y[super 2])
+is a Rayleigh distribution.
+
+The [@http://en.wikipedia.org/wiki/Chi_distribution Chi],
+[@http://en.wikipedia.org/wiki/Rice_distribution Rice]
+and [@http://en.wikipedia.org/wiki/Weibull_distribution Weibull] distributions are generalizations of the
+[@http://en.wikipedia.org/wiki/Rayleigh_distribution Rayleigh distribution].
+
+[h4 Member Functions]
+
+ rayleigh_distribution(RealType sigma = 1);
+
+Constructs a [@http://en.wikipedia.org/wiki/Rayleigh_distribution
+Rayleigh distribution] with [sigma] /sigma/.
+
+Requires that the [sigma] parameter is greater than zero,
+otherwise calls __domain_error.
+
+ RealType sigma()const;
+
+Returns the /sigma/ parameter of this distribution.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] that are generic to all
+distributions are supported: __usual_accessors.
+
+The domain of the random variable is \[0, max_value\].
+
+[h4 Accuracy]
+
+The Rayleigh distribution is implemented in terms of the
+standard library `sqrt` and `exp` and as such should have very low error rates.
+Some constants such as skewness and kurtosis were calculated using
+NTL RR type with 150-bit accuracy, about 50 decimal digits.
+
+[h4 Implementation]
+
+In the following table [sigma][space] is the sigma parameter of the distribution,
+/x/ is the random variate, /p/ is the probability and /q = 1-p/.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Using the relation: pdf = x * exp(-x[super 2])/2 [sigma][super 2] ]]
+[[cdf][Using the relation: p = 1 - exp(-x[super 2]/2) [sigma][super 2][space] = -__expm1(-x[super 2]/2) [sigma][super 2]]]
+[[cdf complement][Using the relation: q = exp(-x[super 2]/ 2) * [sigma][super 2] ]]
+[[quantile][Using the relation: x = sqrt(-2 * [sigma] [super 2]) * log(1 - p)) = sqrt(-2 * [sigma] [super 2]) * __log1p(-p))]]
+[[quantile from the complement][Using the relation: x = sqrt(-2 * [sigma] [super 2]) * log(q)) ]]
+[[mean][[sigma] * sqrt([pi]/2) ]]
+[[variance][[sigma][super 2] * (4 - [pi]/2) ]]
+[[mode][[sigma] ]]
+[[skewness][Constant from [@http://mathworld.wolfram.com/RayleighDistribution.html Weisstein, Eric W. "Weibull Distribution." From MathWorld--A Wolfram Web Resource.] ]]
+[[kurtosis][Constant from [@http://mathworld.wolfram.com/RayleighDistribution.html Weisstein, Eric W. "Weibull Distribution." From MathWorld--A Wolfram Web Resource.] ]]
+[[kurtosis excess][Constant from [@http://mathworld.wolfram.com/RayleighDistribution.html Weisstein, Eric W. "Weibull Distribution." From MathWorld--A Wolfram Web Resource.] ]]
+]
+
+[h4 References]
+* [@http://en.wikipedia.org/wiki/Rayleigh_distribution ]
+* [@http://mathworld.wolfram.com/RayleighDistribution.html Weisstein, Eric W. "Rayleigh Distribution." From MathWorld--A Wolfram Web Resource.]
+
+[endsect] [/section:Rayleigh Rayleigh]
+
+[/
+ 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).
+]
+
diff --git a/doc/distributions/skew_normal.qbk b/doc/distributions/skew_normal.qbk
new file mode 100644
index 0000000..ca12675
--- /dev/null
+++ b/doc/distributions/skew_normal.qbk
@@ -0,0 +1,193 @@
+[section:skew_normal_dist Skew Normal Distribution]
+
+``#include <boost/math/distributions/skew_normal.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class skew_normal_distribution;
+
+ typedef skew_normal_distribution<> normal;
+
+ template <class RealType, class ``__Policy``>
+ class skew_normal_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+ // Constructor:
+ skew_normal_distribution(RealType location = 0, RealType scale = 1, RealType shape = 0);
+ // Accessors:
+ RealType location()const; // mean if normal.
+ RealType scale()const; // width, standard deviation if normal.
+ RealType shape()const; // The distribution is right skewed if shape > 0 and is left skewed if shape < 0.
+ // The distribution is normal if shape is zero.
+ };
+
+ }} // namespaces
+
+The skew normal distribution is a variant of the most well known
+Gaussian statistical distribution.
+
+The skew normal distribution with shape zero resembles the
+[@http://en.wikipedia.org/wiki/Normal_distribution Normal Distribution],
+hence the latter can be regarded as a special case of the more generic skew normal distribution.
+
+If the standard (mean = 0, scale = 1) normal distribution probability density function is
+
+[space][space][equation normal01_pdf]
+
+and the cumulative distribution function
+
+[space][space][equation normal01_cdf]
+
+then the [@http://en.wikipedia.org/wiki/Probability_density_function PDF]
+of the [@http://en.wikipedia.org/wiki/Skew_normal_distribution skew normal distribution]
+with shape parameter [alpha], defined by O'Hagan and Leonhard (1976) is
+
+[space][space][equation skew_normal_pdf0]
+
+Given [@http://en.wikipedia.org/wiki/Location_parameter location] [xi],
+[@http://en.wikipedia.org/wiki/Scale_parameter scale] [omega],
+and [@http://en.wikipedia.org/wiki/Shape_parameter shape] [alpha],
+it can be
+[@http://en.wikipedia.org/wiki/Skew_normal_distribution transformed],
+to the form:
+
+[space][space][equation skew_normal_pdf]
+
+and [@http://en.wikipedia.org/wiki/Cumulative_distribution_function CDF]:
+
+[space][space][equation skew_normal_cdf]
+
+where ['T(h,a)] is Owen's T function, and ['[Phi](x)] is the normal distribution.
+
+The variation the PDF and CDF with its parameters is illustrated
+in the following graphs:
+
+[graph skew_normal_pdf]
+[graph skew_normal_cdf]
+
+[h4 Member Functions]
+
+ skew_normal_distribution(RealType location = 0, RealType scale = 1, RealType shape = 0);
+
+Constructs a skew_normal distribution with location [xi],
+scale [omega] and shape [alpha].
+
+Requires scale > 0, otherwise __domain_error is called.
+
+ RealType location()const;
+
+returns the location [xi] of this distribution,
+
+ RealType scale()const;
+
+returns the scale [omega] of this distribution,
+
+ RealType shape()const;
+
+returns the shape [alpha] of this distribution.
+
+(Location and scale function match other similar distributions,
+allowing the functions `find_location` and `find_scale` to be used generically).
+
+[note While the shape parameter may be chosen arbitrarily (finite),
+the resulting [*skewness] of the distribution is in fact limited to about (-1, 1);
+strictly, the interval is (-0.9952717, 0.9952717).
+
+A parameter [delta] is related to the shape [alpha] by
+[delta] = [alpha] / (1 + [alpha][pow2]),
+and used in the expression for skewness
+[equation skew_normal_skewness]
+] [/note]
+
+[h4 References]
+
+* [@http://azzalini.stat.unipd.it/SN/ Skew-Normal Probability Distribution] for many links and bibliography.
+* [@http://azzalini.stat.unipd.it/SN/Intro/intro.html A very brief introduction to the skew-normal distribution]
+by Adelchi Azzalini (2005-11-2).
+* See a [@http://www.tri.org.au/azzalini.html skew-normal function animation].
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
+that are generic to all distributions are supported: __usual_accessors.
+
+The domain of the random variable is ['-[max_value], +[min_value]].
+Infinite values are not supported.
+
+There are no [@http://en.wikipedia.org/wiki/Closed-form_expression closed-form expression]
+known for the mode and median, but these are computed for the
+
+* mode - by finding the maximum of the PDF.
+* median - by computing `quantile(1/2)`.
+
+The maximum of the PDF is sought through searching the root of f'(x)=0.
+
+Both involve iterative methods that will have lower accuracy than other estimates.
+
+[h4 Testing]
+
+__R using library(sn) described at
+[@http://azzalini.stat.unipd.it/SN/ Skew-Normal Probability Distribution],
+and at [@http://cran.r-project.org/web/packages/sn/sn.pd R skew-normal(sn) package].
+
+Package sn provides functions related to the skew-normal (SN)
+and the skew-t (ST) probability distributions,
+both for the univariate and for the the multivariate case,
+including regression models.
+
+__Mathematica was also used to generate some more accurate spot test data.
+
+[h4 Accuracy]
+
+The skew_normal distribution with shape = zero is implemented as a special case,
+equivalent to the normal distribution in terms of the
+[link math_toolkit.sf_erf.error_function error function],
+and therefore should have excellent accuracy.
+
+The PDF and mean, variance, skewness and kurtosis are also accurately evaluated using
+[@http://en.wikipedia.org/wiki/Analytical_expression analytical expressions].
+The CDF requires [@http://en.wikipedia.org/wiki/Owen%27s_T_function Owen's T function]
+that is evaluated using a Boost C++ __owens_t implementation of the algorithms of
+M. Patefield and D. Tandy, Journal of Statistical Software, 5(5), 1-25 (2000);
+the complicated accuracy of this function is discussed in detail at __owens_t.
+
+The median and mode are calculated by iterative root finding, and both will be less accurate.
+
+[h4 Implementation]
+
+In the following table, [xi] is the location of the distribution,
+and [omega] is its scale, and [alpha] is its shape.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Using:[equation skew_normal_pdf] ]]
+[[cdf][Using: [equation skew_normal_cdf][br]
+where ['T(h,a)] is Owen's T function, and ['[Phi](x)] is the normal distribution. ]]
+[[cdf complement][Using: complement of normal distribution + 2 * Owens_t]]
+[[quantile][Maximum of the pdf is sought through searching the root of f'(x)=0]]
+[[quantile from the complement][-quantile(SN(-location [xi], scale [omega], -shape[alpha]), p)]]
+[[location][location [xi]]]
+[[scale][scale [omega]]]
+[[shape][shape [alpha]]]
+[[median][quantile(1/2)]]
+[[mean][[equation skew_normal_mean]]]
+[[mode][Maximum of the pdf is sought through searching the root of f'(x)=0]]
+[[variance][[equation skew_normal_variance] ]]
+[[skewness][[equation skew_normal_skewness] ]]
+[[kurtosis][kurtosis excess-3]]
+[[kurtosis excess] [ [equation skew_normal_kurt_ex] ]]
+] [/table]
+
+[endsect] [/section:skew_normal_dist skew_Normal]
+
+[/ skew_normal.qbk
+ Copyright 2012 Bejamin Sobotta, 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).
+]
+
diff --git a/doc/distributions/students_t.qbk b/doc/distributions/students_t.qbk
new file mode 100644
index 0000000..d9146e5
--- /dev/null
+++ b/doc/distributions/students_t.qbk
@@ -0,0 +1,188 @@
+[section:students_t_dist Students t Distribution]
+
+``#include <boost/math/distributions/students_t.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class students_t_distribution;
+
+ typedef students_t_distribution<> students_t;
+
+ template <class RealType, class ``__Policy``>
+ class students_t_distribution
+ {
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ // Constructor:
+ students_t_distribution(const RealType& v);
+
+ // Accessor:
+ RealType degrees_of_freedom()const;
+
+ // degrees of freedom estimation:
+ static RealType find_degrees_of_freedom(
+ RealType difference_from_mean,
+ RealType alpha,
+ RealType beta,
+ RealType sd,
+ RealType hint = 100);
+ };
+
+ }} // namespaces
+
+Student's t-distribution is a statistical distribution published by William Gosset in 1908.
+His employer, Guinness Breweries, required him to publish under a
+pseudonym (possibly to hide that they were using statistics to improve beer quality),
+so he chose "Student".
+
+Given N independent measurements, let
+
+[equation students_t_dist]
+
+where /M/ is the population mean, [' ''' μ '''] is the sample mean, and /s/ is the
+sample variance.
+
+[@https://en.wikipedia.org/wiki/Student%27s_t-distribution Student's t-distribution]
+is defined as the distribution of the random
+variable t which is - very loosely - the "best" that we can do not
+knowing the true standard deviation of the sample. It has the PDF:
+
+[equation students_t_ref1]
+
+The Student's t-distribution takes a single parameter: the number of
+degrees of freedom of the sample. When the degrees of freedom is
+/one/ then this distribution is the same as the Cauchy-distribution.
+As the number of degrees of freedom tends towards infinity, then this
+distribution approaches the normal-distribution. The following graph
+illustrates how the PDF varies with the degrees of freedom [nu]:
+
+[graph students_t_pdf]
+
+[h4 Member Functions]
+
+ students_t_distribution(const RealType& v);
+
+Constructs a Student's t-distribution with /v/ degrees of freedom.
+
+Requires /v/ > 0, including infinity (if RealType permits),
+otherwise calls __domain_error. Note that
+non-integral degrees of freedom are supported,
+and are meaningful under certain circumstances.
+
+ RealType degrees_of_freedom()const;
+
+returns the number of degrees of freedom of this distribution.
+
+ static RealType find_degrees_of_freedom(
+ RealType difference_from_mean,
+ RealType alpha,
+ RealType beta,
+ RealType sd,
+ RealType hint = 100);
+
+returns the number of degrees of freedom required to observe a significant
+result in the Student's t test when the mean differs from the "true"
+mean by /difference_from_mean/.
+
+[variablelist
+[[difference_from_mean][The difference between the true mean and the sample mean
+ that we wish to show is significant.]]
+[[alpha][The maximum acceptable probability of rejecting the null hypothesis
+ when it is in fact true.]]
+[[beta][The maximum acceptable probability of failing to reject the null hypothesis
+ when it is in fact false.]]
+[[sd][The sample standard deviation.]]
+[[hint][A hint for the location to start looking for the result, a good choice for this
+ would be the sample size of a previous borderline Student's t test.]]
+]
+
+[note
+Remember that for a two-sided test, you must divide alpha by two
+before calling this function.]
+
+For more information on this function see the
+[@http://www.itl.nist.gov/div898/handbook/prc/section2/prc222.htm
+NIST Engineering Statistics Handbook].
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] that are generic to all
+distributions are supported: __usual_accessors.
+
+The domain of the random variable is \[-[infin], +[infin]\].
+
+[h4 Examples]
+
+Various [link math_toolkit.stat_tut.weg.st_eg worked examples] are available illustrating the use of the Student's t
+distribution.
+
+[h4 Accuracy]
+
+The normal distribution is implemented in terms of the
+[link math_toolkit.sf_beta.ibeta_function incomplete beta function]
+and [link math_toolkit.sf_beta.ibeta_inv_function its inverses],
+refer to accuracy data on those functions for more information.
+
+[h4 Implementation]
+
+In the following table /v/ is the degrees of freedom of the distribution,
+/t/ is the random variate, /p/ is the probability and /q = 1-p/.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Using the relation: pdf = (v \/ (v + t[super 2]))[super (1+v)\/2 ] / (sqrt(v) * __beta(v\/2, 0.5)) ]]
+[[cdf][Using the relations:
+
+p = 1 - z /iff t > 0/
+
+p = z /otherwise/
+
+where z is given by:
+
+__ibeta(v \/ 2, 0.5, v \/ (v + t[super 2])) \/ 2 ['iff v < 2t[super 2]]
+
+__ibetac(0.5, v \/ 2, t[super 2 ] / (v + t[super 2]) \/ 2 /otherwise/]]
+[[cdf complement][Using the relation: q = cdf(-t) ]]
+[[quantile][Using the relation: t = sign(p - 0.5) * sqrt(v * y \/ x)
+
+where:
+
+x = __ibeta_inv(v \/ 2, 0.5, 2 * min(p, q))
+
+y = 1 - x
+
+The quantities /x/ and /y/ are both returned by __ibeta_inv
+without the subtraction implied above.]]
+[[quantile from the complement][Using the relation: t = -quantile(q)]]
+[[mode][0]]
+[[mean][0]]
+[[variance][if (v > 2) v \/ (v - 2) else NaN]]
+[[skewness][if (v > 3) 0 else NaN ]]
+[[kurtosis][if (v > 4) 3 * (v - 2) \/ (v - 4) else NaN]]
+[[kurtosis excess][if (v > 4) 6 \/ (df - 4) else NaN]]
+]
+
+If the moment index /k/ is less than /v/, then the moment is undefined.
+Evaluating the moment will throw a __domain_error unless ignored by a policy,
+when it will return `std::numeric_limits<>::quiet_NaN();`
+
+[h5:implementation Implementation]
+
+(By popular demand, we now support infinite argument and random deviate.
+But we have not implemented the return of infinity
+as suggested by [@http://en.wikipedia.org/wiki/Student%27s_t-distribution Wikipedia Student's t],
+instead throwing a domain error or return NaN.
+See also [@https://svn.boost.org/trac/boost/ticket/7177].)
+
+[endsect] [/section:students_t_dist Students t]
+
+[/ students_t.qbk
+ Copyright 2006, 2012, 2017 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).
+]
+
diff --git a/doc/distributions/students_t_examples.qbk b/doc/distributions/students_t_examples.qbk
new file mode 100644
index 0000000..483631e
--- /dev/null
+++ b/doc/distributions/students_t_examples.qbk
@@ -0,0 +1,781 @@
+
+[section:st_eg Student's t Distribution Examples]
+
+[section:tut_mean_intervals Calculating confidence intervals on the mean with the Students-t distribution]
+
+Let's say you have a sample mean, you may wish to know what confidence intervals
+you can place on that mean. Colloquially: "I want an interval that I can be
+P% sure contains the true mean". (On a technical point, note that
+the interval either contains the true mean or it does not: the
+meaning of the confidence level is subtly
+different from this colloquialism. More background information can be found on the
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda352.htm NIST site]).
+
+The formula for the interval can be expressed as:
+
+[equation dist_tutorial4]
+
+Where, ['Y[sub s]] is the sample mean, /s/ is the sample standard deviation,
+/N/ is the sample size, /[alpha]/ is the desired significance level and
+['t[sub ([alpha]/2,N-1)]] is the upper critical value of the Students-t
+distribution with /N-1/ degrees of freedom.
+
+[note
+The quantity [alpha][space] is the maximum acceptable risk of falsely rejecting
+the null-hypothesis. The smaller the value of [alpha] the greater the
+strength of the test.
+
+The confidence level of the test is defined as 1 - [alpha], and often expressed
+as a percentage. So for example a significance level of 0.05, is equivalent
+to a 95% confidence level. Refer to
+[@http://www.itl.nist.gov/div898/handbook/prc/section1/prc14.htm
+"What are confidence intervals?"] in __handbook for more information.
+] [/ Note]
+
+[note
+The usual assumptions of
+[@http://en.wikipedia.org/wiki/Independent_and_identically-distributed_random_variables independent and identically distributed (i.i.d.)]
+variables and [@http://en.wikipedia.org/wiki/Normal_distribution normal distribution]
+of course apply here, as they do in other examples.
+]
+
+From the formula, it should be clear that:
+
+* The width of the confidence interval decreases as the sample size increases.
+* The width increases as the standard deviation increases.
+* The width increases as the ['confidence level increases] (0.5 towards 0.99999 - stronger).
+* The width increases as the ['significance level decreases] (0.5 towards 0.00000...01 - stronger).
+
+The following example code is taken from the example program
+[@../../example/students_t_single_sample.cpp students_t_single_sample.cpp].
+
+We'll begin by defining a procedure to calculate intervals for
+various confidence levels; the procedure will print these out
+as a table:
+
+ // Needed includes:
+ #include <boost/math/distributions/students_t.hpp>
+ #include <iostream>
+ #include <iomanip>
+ // Bring everything into global namespace for ease of use:
+ using namespace boost::math;
+ using namespace std;
+
+ void confidence_limits_on_mean(
+ double Sm, // Sm = Sample Mean.
+ double Sd, // Sd = Sample Standard Deviation.
+ unsigned Sn) // Sn = Sample Size.
+ {
+ using namespace std;
+ using namespace boost::math;
+
+ // Print out general info:
+ cout <<
+ "__________________________________\n"
+ "2-Sided Confidence Limits For Mean\n"
+ "__________________________________\n\n";
+ cout << setprecision(7);
+ cout << setw(40) << left << "Number of Observations" << "= " << Sn << "\n";
+ cout << setw(40) << left << "Mean" << "= " << Sm << "\n";
+ cout << setw(40) << left << "Standard Deviation" << "= " << Sd << "\n";
+
+We'll define a table of significance/risk levels for which we'll compute intervals:
+
+ double alpha[] = { 0.5, 0.25, 0.1, 0.05, 0.01, 0.001, 0.0001, 0.00001 };
+
+Note that these are the complements of the confidence/probability levels: 0.5, 0.75, 0.9 .. 0.99999).
+
+Next we'll declare the distribution object we'll need, note that
+the /degrees of freedom/ parameter is the sample size less one:
+
+ students_t dist(Sn - 1);
+
+Most of what follows in the program is pretty printing, so let's focus
+on the calculation of the interval. First we need the t-statistic,
+computed using the /quantile/ function and our significance level. Note
+that since the significance levels are the complement of the probability,
+we have to wrap the arguments in a call to /complement(...)/:
+
+ double T = quantile(complement(dist, alpha[i] / 2));
+
+Note that alpha was divided by two, since we'll be calculating
+both the upper and lower bounds: had we been interested in a single
+sided interval then we would have omitted this step.
+
+Now to complete the picture, we'll get the (one-sided) width of the
+interval from the t-statistic
+by multiplying by the standard deviation, and dividing by the square
+root of the sample size:
+
+ double w = T * Sd / sqrt(double(Sn));
+
+The two-sided interval is then the sample mean plus and minus this width.
+
+And apart from some more pretty-printing that completes the procedure.
+
+Let's take a look at some sample output, first using the
+[@http://www.itl.nist.gov/div898/handbook/eda/section4/eda428.htm
+Heat flow data] from the NIST site. The data set was collected
+by Bob Zarr of NIST in January, 1990 from a heat flow meter
+calibration and stability analysis.
+The corresponding dataplot
+output for this test can be found in
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda352.htm
+section 3.5.2] of the __handbook.
+
+[pre'''
+ __________________________________
+ 2-Sided Confidence Limits For Mean
+ __________________________________
+
+ Number of Observations = 195
+ Mean = 9.26146
+ Standard Deviation = 0.02278881
+
+
+ ___________________________________________________________________
+ Confidence T Interval Lower Upper
+ Value (%) Value Width Limit Limit
+ ___________________________________________________________________
+ 50.000 0.676 1.103e-003 9.26036 9.26256
+ 75.000 1.154 1.883e-003 9.25958 9.26334
+ 90.000 1.653 2.697e-003 9.25876 9.26416
+ 95.000 1.972 3.219e-003 9.25824 9.26468
+ 99.000 2.601 4.245e-003 9.25721 9.26571
+ 99.900 3.341 5.453e-003 9.25601 9.26691
+ 99.990 3.973 6.484e-003 9.25498 9.26794
+ 99.999 4.537 7.404e-003 9.25406 9.26886
+''']
+
+As you can see the large sample size (195) and small standard deviation (0.023)
+have combined to give very small intervals, indeed we can be
+very confident that the true mean is 9.2.
+
+For comparison the next example data output is taken from
+['P.K.Hou, O. W. Lau & M.C. Wong, Analyst (1983) vol. 108, p 64.
+and from Statistics for Analytical Chemistry, 3rd ed. (1994), pp 54-55
+J. C. Miller and J. N. Miller, Ellis Horwood ISBN 0 13 0309907.]
+The values result from the determination of mercury by cold-vapour
+atomic absorption.
+
+[pre'''
+ __________________________________
+ 2-Sided Confidence Limits For Mean
+ __________________________________
+
+ Number of Observations = 3
+ Mean = 37.8000000
+ Standard Deviation = 0.9643650
+
+
+ ___________________________________________________________________
+ Confidence T Interval Lower Upper
+ Value (%) Value Width Limit Limit
+ ___________________________________________________________________
+ 50.000 0.816 0.455 37.34539 38.25461
+ 75.000 1.604 0.893 36.90717 38.69283
+ 90.000 2.920 1.626 36.17422 39.42578
+ 95.000 4.303 2.396 35.40438 40.19562
+ 99.000 9.925 5.526 32.27408 43.32592
+ 99.900 31.599 17.594 20.20639 55.39361
+ 99.990 99.992 55.673 -17.87346 93.47346
+ 99.999 316.225 176.067 -138.26683 213.86683
+''']
+
+This time the fact that there are only three measurements leads to
+much wider intervals, indeed such large intervals that it's hard
+to be very confident in the location of the mean.
+
+[endsect]
+
+[section:tut_mean_test Testing a sample mean for difference from a "true" mean]
+
+When calibrating or comparing a scientific instrument or measurement method of some kind,
+we want to be answer the question "Does an observed sample mean differ from the
+"true" mean in any significant way?". If it does, then we have evidence of
+a systematic difference. This question can be answered with a Students-t test:
+more information can be found
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda352.htm
+on the NIST site].
+
+Of course, the assignment of "true" to one mean may be quite arbitrary,
+often this is simply a "traditional" method of measurement.
+
+The following example code is taken from the example program
+[@../../example/students_t_single_sample.cpp students_t_single_sample.cpp].
+
+We'll begin by defining a procedure to determine which of the
+possible hypothesis are rejected or not-rejected
+at a given significance level:
+
+[note
+Non-statisticians might say 'not-rejected' means 'accepted',
+(often of the null-hypothesis) implying, wrongly, that there really *IS* no difference,
+but statisticans eschew this to avoid implying that there is positive evidence of 'no difference'.
+'Not-rejected' here means there is *no evidence* of difference, but there still might well be a difference.
+For example, see [@http://en.wikipedia.org/wiki/Argument_from_ignorance argument from ignorance] and
+[@http://www.bmj.com/cgi/content/full/311/7003/485 Absence of evidence does not constitute evidence of absence.]
+] [/ note]
+
+
+ // Needed includes:
+ #include <boost/math/distributions/students_t.hpp>
+ #include <iostream>
+ #include <iomanip>
+ // Bring everything into global namespace for ease of use:
+ using namespace boost::math;
+ using namespace std;
+
+ void single_sample_t_test(double M, double Sm, double Sd, unsigned Sn, double alpha)
+ {
+ //
+ // M = true mean.
+ // Sm = Sample Mean.
+ // Sd = Sample Standard Deviation.
+ // Sn = Sample Size.
+ // alpha = Significance Level.
+
+Most of the procedure is pretty-printing, so let's just focus on the
+calculation, we begin by calculating the t-statistic:
+
+ // Difference in means:
+ double diff = Sm - M;
+ // Degrees of freedom:
+ unsigned v = Sn - 1;
+ // t-statistic:
+ double t_stat = diff * sqrt(double(Sn)) / Sd;
+
+Finally calculate the probability from the t-statistic. If we're interested
+in simply whether there is a difference (either less or greater) or not,
+we don't care about the sign of the t-statistic,
+and we take the complement of the probability for comparison
+to the significance level:
+
+ students_t dist(v);
+ double q = cdf(complement(dist, fabs(t_stat)));
+
+The procedure then prints out the results of the various tests
+that can be done, these
+can be summarised in the following table:
+
+[table
+[[Hypothesis][Test]]
+[[The Null-hypothesis: there is
+*no difference* in means]
+[Reject if complement of CDF for |t| < significance level / 2:
+
+`cdf(complement(dist, fabs(t))) < alpha / 2`]]
+
+[[The Alternative-hypothesis: there
+*is difference* in means]
+[Reject if complement of CDF for |t| > significance level / 2:
+
+`cdf(complement(dist, fabs(t))) > alpha / 2`]]
+
+[[The Alternative-hypothesis: the sample mean *is less* than
+the true mean.]
+[Reject if CDF of t > 1 - significance level:
+
+`cdf(complement(dist, t)) < alpha`]]
+
+[[The Alternative-hypothesis: the sample mean *is greater* than
+the true mean.]
+[Reject if complement of CDF of t < significance level:
+
+`cdf(dist, t) < alpha`]]
+]
+
+[note
+Notice that the comparisons are against `alpha / 2` for a two-sided test
+and against `alpha` for a one-sided test]
+
+Now that we have all the parts in place, let's take a look at some
+sample output, first using the
+[@http://www.itl.nist.gov/div898/handbook/eda/section4/eda428.htm
+Heat flow data] from the NIST site. The data set was collected
+by Bob Zarr of NIST in January, 1990 from a heat flow meter
+calibration and stability analysis. The corresponding dataplot
+output for this test can be found in
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda352.htm
+section 3.5.2] of the __handbook.
+
+[pre
+__________________________________
+Student t test for a single sample
+__________________________________
+
+Number of Observations = 195
+Sample Mean = 9.26146
+Sample Standard Deviation = 0.02279
+Expected True Mean = 5.00000
+
+Sample Mean - Expected Test Mean = 4.26146
+Degrees of Freedom = 194
+T Statistic = 2611.28380
+Probability that difference is due to chance = 0.000e+000
+
+Results for Alternative Hypothesis and alpha = 0.0500
+
+Alternative Hypothesis Conclusion
+Mean != 5.000 NOT REJECTED
+Mean < 5.000 REJECTED
+Mean > 5.000 NOT REJECTED
+]
+
+You will note the line that says the probability that the difference is
+due to chance is zero. From a philosophical point of view, of course,
+the probability can never reach zero. However, in this case the calculated
+probability is smaller than the smallest representable double precision number,
+hence the appearance of a zero here. Whatever its "true" value is, we know it
+must be extraordinarily small, so the alternative hypothesis - that there is
+a difference in means - is not rejected.
+
+For comparison the next example data output is taken from
+['P.K.Hou, O. W. Lau & M.C. Wong, Analyst (1983) vol. 108, p 64.
+and from Statistics for Analytical Chemistry, 3rd ed. (1994), pp 54-55
+J. C. Miller and J. N. Miller, Ellis Horwood ISBN 0 13 0309907.]
+The values result from the determination of mercury by cold-vapour
+atomic absorption.
+
+[pre
+__________________________________
+Student t test for a single sample
+__________________________________
+
+Number of Observations = 3
+Sample Mean = 37.80000
+Sample Standard Deviation = 0.96437
+Expected True Mean = 38.90000
+
+Sample Mean - Expected Test Mean = -1.10000
+Degrees of Freedom = 2
+T Statistic = -1.97566
+Probability that difference is due to chance = 1.869e-001
+
+Results for Alternative Hypothesis and alpha = 0.0500
+
+Alternative Hypothesis Conclusion
+Mean != 38.900 REJECTED
+Mean < 38.900 NOT REJECTED
+Mean > 38.900 NOT REJECTED
+]
+
+As you can see the small number of measurements (3) has led to a large uncertainty
+in the location of the true mean. So even though there appears to be a difference
+between the sample mean and the expected true mean, we conclude that there
+is no significant difference, and are unable to reject the null hypothesis.
+However, if we were to lower the bar for acceptance down to alpha = 0.1
+(a 90% confidence level) we see a different output:
+
+[pre
+__________________________________
+Student t test for a single sample
+__________________________________
+
+Number of Observations = 3
+Sample Mean = 37.80000
+Sample Standard Deviation = 0.96437
+Expected True Mean = 38.90000
+
+Sample Mean - Expected Test Mean = -1.10000
+Degrees of Freedom = 2
+T Statistic = -1.97566
+Probability that difference is due to chance = 1.869e-001
+
+Results for Alternative Hypothesis and alpha = 0.1000
+
+Alternative Hypothesis Conclusion
+Mean != 38.900 REJECTED
+Mean < 38.900 NOT REJECTED
+Mean > 38.900 REJECTED
+]
+
+In this case, we really have a borderline result,
+and more data (and/or more accurate data),
+is needed for a more convincing conclusion.
+
+[endsect]
+
+[section:tut_mean_size Estimating how large a sample size would have to become
+in order to give a significant Students-t test result with a single sample test]
+
+Imagine you have conducted a Students-t test on a single sample in order
+to check for systematic errors in your measurements. Imagine that the
+result is borderline. At this point one might go off and collect more data,
+but it might be prudent to first ask the question "How much more?".
+The parameter estimators of the students_t_distribution class
+can provide this information.
+
+This section is based on the example code in
+[@../../example/students_t_single_sample.cpp students_t_single_sample.cpp]
+and we begin by defining a procedure that will print out a table of
+estimated sample sizes for various confidence levels:
+
+ // Needed includes:
+ #include <boost/math/distributions/students_t.hpp>
+ #include <iostream>
+ #include <iomanip>
+ // Bring everything into global namespace for ease of use:
+ using namespace boost::math;
+ using namespace std;
+
+ void single_sample_find_df(
+ double M, // M = true mean.
+ double Sm, // Sm = Sample Mean.
+ double Sd) // Sd = Sample Standard Deviation.
+ {
+
+Next we define a table of significance levels:
+
+ double alpha[] = { 0.5, 0.25, 0.1, 0.05, 0.01, 0.001, 0.0001, 0.00001 };
+
+Printing out the table of sample sizes required for various confidence levels
+begins with the table header:
+
+ cout << "\n\n"
+ "_______________________________________________________________\n"
+ "Confidence Estimated Estimated\n"
+ " Value (%) Sample Size Sample Size\n"
+ " (one sided test) (two sided test)\n"
+ "_______________________________________________________________\n";
+
+
+And now the important part: the sample sizes required. Class
+`students_t_distribution` has a static member function
+`find_degrees_of_freedom` that will calculate how large
+a sample size needs to be in order to give a definitive result.
+
+The first argument is the difference between the means that you
+wish to be able to detect, here it's the absolute value of the
+difference between the sample mean, and the true mean.
+
+Then come two probability values: alpha and beta. Alpha is the
+maximum acceptable risk of rejecting the null-hypothesis when it is
+in fact true. Beta is the maximum acceptable risk of failing to reject
+the null-hypothesis when in fact it is false.
+Also note that for a two-sided test, alpha must be divided by 2.
+
+The final parameter of the function is the standard deviation of the sample.
+
+In this example, we assume that alpha and beta are the same, and call
+`find_degrees_of_freedom` twice: once with alpha for a one-sided test,
+and once with alpha/2 for a two-sided test.
+
+ for(unsigned i = 0; i < sizeof(alpha)/sizeof(alpha[0]); ++i)
+ {
+ // Confidence value:
+ cout << fixed << setprecision(3) << setw(10) << right << 100 * (1-alpha[i]);
+ // calculate df for single sided test:
+ double df = students_t::find_degrees_of_freedom(
+ fabs(M - Sm), alpha[i], alpha[i], Sd);
+ // convert to sample size:
+ double size = ceil(df) + 1;
+ // Print size:
+ cout << fixed << setprecision(0) << setw(16) << right << size;
+ // calculate df for two sided test:
+ df = students_t::find_degrees_of_freedom(
+ fabs(M - Sm), alpha[i]/2, alpha[i], Sd);
+ // convert to sample size:
+ size = ceil(df) + 1;
+ // Print size:
+ cout << fixed << setprecision(0) << setw(16) << right << size << endl;
+ }
+ cout << endl;
+ }
+
+Let's now look at some sample output using data taken from
+['P.K.Hou, O. W. Lau & M.C. Wong, Analyst (1983) vol. 108, p 64.
+and from Statistics for Analytical Chemistry, 3rd ed. (1994), pp 54-55
+J. C. Miller and J. N. Miller, Ellis Horwood ISBN 0 13 0309907.]
+The values result from the determination of mercury by cold-vapour
+atomic absorption.
+
+Only three measurements were made, and the Students-t test above
+gave a borderline result, so this example
+will show us how many samples would need to be collected:
+
+[pre'''
+_____________________________________________________________
+Estimated sample sizes required for various confidence levels
+_____________________________________________________________
+
+True Mean = 38.90000
+Sample Mean = 37.80000
+Sample Standard Deviation = 0.96437
+
+
+_______________________________________________________________
+Confidence Estimated Estimated
+ Value (%) Sample Size Sample Size
+ (one sided test) (two sided test)
+_______________________________________________________________
+ 75.000 3 4
+ 90.000 7 9
+ 95.000 11 13
+ 99.000 20 22
+ 99.900 35 37
+ 99.990 50 53
+ 99.999 66 68
+''']
+
+So in this case, many more measurements would have had to be made,
+for example at the 95% level, 14 measurements in total for a two-sided test.
+
+[endsect]
+[section:two_sample_students_t Comparing the means of two samples with the Students-t test]
+
+Imagine that we have two samples, and we wish to determine whether
+their means are different or not. This situation often arises when
+determining whether a new process or treatment is better than an old one.
+
+In this example, we'll be using the
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda3531.htm
+Car Mileage sample data] from the
+[@http://www.itl.nist.gov NIST website]. The data compares
+miles per gallon of US cars with miles per gallon of Japanese cars.
+
+The sample code is in
+[@../../example/students_t_two_samples.cpp students_t_two_samples.cpp].
+
+There are two ways in which this test can be conducted: we can assume
+that the true standard deviations of the two samples are equal or not.
+If the standard deviations are assumed to be equal, then the calculation
+of the t-statistic is greatly simplified, so we'll examine that case first.
+In real life we should verify whether this assumption is valid with a
+Chi-Squared test for equal variances.
+
+We begin by defining a procedure that will conduct our test assuming equal
+variances:
+
+ // Needed headers:
+ #include <boost/math/distributions/students_t.hpp>
+ #include <iostream>
+ #include <iomanip>
+ // Simplify usage:
+ using namespace boost::math;
+ using namespace std;
+
+ void two_samples_t_test_equal_sd(
+ double Sm1, // Sm1 = Sample 1 Mean.
+ double Sd1, // Sd1 = Sample 1 Standard Deviation.
+ unsigned Sn1, // Sn1 = Sample 1 Size.
+ double Sm2, // Sm2 = Sample 2 Mean.
+ double Sd2, // Sd2 = Sample 2 Standard Deviation.
+ unsigned Sn2, // Sn2 = Sample 2 Size.
+ double alpha) // alpha = Significance Level.
+ {
+
+
+Our procedure will begin by calculating the t-statistic, assuming
+equal variances the needed formulae are:
+
+[equation dist_tutorial1]
+
+where Sp is the "pooled" standard deviation of the two samples,
+and /v/ is the number of degrees of freedom of the two combined
+samples. We can now write the code to calculate the t-statistic:
+
+ // Degrees of freedom:
+ double v = Sn1 + Sn2 - 2;
+ cout << setw(55) << left << "Degrees of Freedom" << "= " << v << "\n";
+ // Pooled variance:
+ double sp = sqrt(((Sn1-1) * Sd1 * Sd1 + (Sn2-1) * Sd2 * Sd2) / v);
+ cout << setw(55) << left << "Pooled Standard Deviation" << "= " << sp << "\n";
+ // t-statistic:
+ double t_stat = (Sm1 - Sm2) / (sp * sqrt(1.0 / Sn1 + 1.0 / Sn2));
+ cout << setw(55) << left << "T Statistic" << "= " << t_stat << "\n";
+
+The next step is to define our distribution object, and calculate the
+complement of the probability:
+
+ students_t dist(v);
+ double q = cdf(complement(dist, fabs(t_stat)));
+ cout << setw(55) << left << "Probability that difference is due to chance" << "= "
+ << setprecision(3) << scientific << 2 * q << "\n\n";
+
+Here we've used the absolute value of the t-statistic, because we initially
+want to know simply whether there is a difference or not (a two-sided test).
+However, we can also test whether the mean of the second sample is greater
+or is less (one-sided test) than that of the first:
+all the possible tests are summed up in the following table:
+
+[table
+[[Hypothesis][Test]]
+[[The Null-hypothesis: there is
+*no difference* in means]
+[Reject if complement of CDF for |t| < significance level / 2:
+
+`cdf(complement(dist, fabs(t))) < alpha / 2`]]
+
+[[The Alternative-hypothesis: there is a
+*difference* in means]
+[Reject if complement of CDF for |t| > significance level / 2:
+
+`cdf(complement(dist, fabs(t))) < alpha / 2`]]
+
+[[The Alternative-hypothesis: Sample 1 Mean is *less* than
+Sample 2 Mean.]
+[Reject if CDF of t > significance level:
+
+`cdf(dist, t) > alpha`]]
+
+[[The Alternative-hypothesis: Sample 1 Mean is *greater* than
+Sample 2 Mean.]
+
+[Reject if complement of CDF of t > significance level:
+
+`cdf(complement(dist, t)) > alpha`]]
+]
+
+[note
+For a two-sided test we must compare against alpha / 2 and not alpha.]
+
+Most of the rest of the sample program is pretty-printing, so we'll
+skip over that, and take a look at the sample output for alpha=0.05
+(a 95% probability level). For comparison the dataplot output
+for the same data is in
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda353.htm
+section 1.3.5.3] of the __handbook.
+
+[pre'''
+ ________________________________________________
+ Student t test for two samples (equal variances)
+ ________________________________________________
+
+ Number of Observations (Sample 1) = 249
+ Sample 1 Mean = 20.145
+ Sample 1 Standard Deviation = 6.4147
+ Number of Observations (Sample 2) = 79
+ Sample 2 Mean = 30.481
+ Sample 2 Standard Deviation = 6.1077
+ Degrees of Freedom = 326
+ Pooled Standard Deviation = 6.3426
+ T Statistic = -12.621
+ Probability that difference is due to chance = 5.273e-030
+
+ Results for Alternative Hypothesis and alpha = 0.0500'''
+
+ Alternative Hypothesis Conclusion
+ Sample 1 Mean != Sample 2 Mean NOT REJECTED
+ Sample 1 Mean < Sample 2 Mean NOT REJECTED
+ Sample 1 Mean > Sample 2 Mean REJECTED
+]
+
+So with a probability that the difference is due to chance of just
+5.273e-030, we can safely conclude that there is indeed a difference.
+
+The tests on the alternative hypothesis show that we must
+also reject the hypothesis that Sample 1 Mean is
+greater than that for Sample 2: in this case Sample 1 represents the
+miles per gallon for Japanese cars, and Sample 2 the miles per gallon for
+US cars, so we conclude that Japanese cars are on average more
+fuel efficient.
+
+Now that we have the simple case out of the way, let's look for a moment
+at the more complex one: that the standard deviations of the two samples
+are not equal. In this case the formula for the t-statistic becomes:
+
+[equation dist_tutorial2]
+
+And for the combined degrees of freedom we use the
+[@http://en.wikipedia.org/wiki/Welch-Satterthwaite_equation Welch-Satterthwaite]
+approximation:
+
+[equation dist_tutorial3]
+
+Note that this is one of the rare situations where the degrees-of-freedom
+parameter to the Student's t distribution is a real number, and not an
+integer value.
+
+[note
+Some statistical packages truncate the effective degrees of freedom to
+an integer value: this may be necessary if you are relying on lookup tables,
+but since our code fully supports non-integer degrees of freedom there is no
+need to truncate in this case. Also note that when the degrees of freedom
+is small then the Welch-Satterthwaite approximation may be a significant
+source of error.]
+
+Putting these formulae into code we get:
+
+ // Degrees of freedom:
+ double v = Sd1 * Sd1 / Sn1 + Sd2 * Sd2 / Sn2;
+ v *= v;
+ double t1 = Sd1 * Sd1 / Sn1;
+ t1 *= t1;
+ t1 /= (Sn1 - 1);
+ double t2 = Sd2 * Sd2 / Sn2;
+ t2 *= t2;
+ t2 /= (Sn2 - 1);
+ v /= (t1 + t2);
+ cout << setw(55) << left << "Degrees of Freedom" << "= " << v << "\n";
+ // t-statistic:
+ double t_stat = (Sm1 - Sm2) / sqrt(Sd1 * Sd1 / Sn1 + Sd2 * Sd2 / Sn2);
+ cout << setw(55) << left << "T Statistic" << "= " << t_stat << "\n";
+
+Thereafter the code and the tests are performed the same as before. Using
+are car mileage data again, here's what the output looks like:
+
+[pre'''
+ __________________________________________________
+ Student t test for two samples (unequal variances)
+ __________________________________________________
+
+ Number of Observations (Sample 1) = 249
+ Sample 1 Mean = 20.145
+ Sample 1 Standard Deviation = 6.4147
+ Number of Observations (Sample 2) = 79
+ Sample 2 Mean = 30.481
+ Sample 2 Standard Deviation = 6.1077
+ Degrees of Freedom = 136.87
+ T Statistic = -12.946
+ Probability that difference is due to chance = 1.571e-025
+
+ Results for Alternative Hypothesis and alpha = 0.0500'''
+
+ Alternative Hypothesis Conclusion
+ Sample 1 Mean != Sample 2 Mean NOT REJECTED
+ Sample 1 Mean < Sample 2 Mean NOT REJECTED
+ Sample 1 Mean > Sample 2 Mean REJECTED
+]
+
+This time allowing the variances in the two samples to differ has yielded
+a higher likelihood that the observed difference is down to chance alone
+(1.571e-025 compared to 5.273e-030 when equal variances were assumed).
+However, the conclusion remains the same: US cars are less fuel efficient
+than Japanese models.
+
+[endsect]
+[section:paired_st Comparing two paired samples with the Student's t distribution]
+
+Imagine that we have a before and after reading for each item in the sample:
+for example we might have measured blood pressure before and after administration
+of a new drug. We can't pool the results and compare the means before and after
+the change, because each patient will have a different baseline reading.
+Instead we calculate the difference between before and after measurements
+in each patient, and calculate the mean and standard deviation of the differences.
+To test whether a significant change has taken place, we can then test
+the null-hypothesis that the true mean is zero using the same procedure
+we used in the single sample cases previously discussed.
+
+That means we can:
+
+* [link math_toolkit.stat_tut.weg.st_eg.tut_mean_intervals Calculate confidence intervals of the mean].
+If the endpoints of the interval differ in sign then we are unable to reject
+the null-hypothesis that there is no change.
+* [link math_toolkit.stat_tut.weg.st_eg.tut_mean_test Test whether the true mean is zero]. If the
+result is consistent with a true mean of zero, then we are unable to reject the
+null-hypothesis that there is no change.
+* [link math_toolkit.stat_tut.weg.st_eg.tut_mean_size Calculate how many pairs of readings we would need
+in order to obtain a significant result].
+
+[endsect]
+
+[endsect][/section:st_eg Student's t]
+
+[/
+ Copyright 2006, 2012 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).
+]
+
diff --git a/doc/distributions/triangular.qbk b/doc/distributions/triangular.qbk
new file mode 100644
index 0000000..59c6329
--- /dev/null
+++ b/doc/distributions/triangular.qbk
@@ -0,0 +1,179 @@
+[section:triangular_dist Triangular Distribution]
+
+
+``#include <boost/math/distributions/triangular.hpp>``
+
+ namespace boost{ namespace math{
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class triangular_distribution;
+
+ typedef triangular_distribution<> triangular;
+
+ template <class RealType, class ``__Policy``>
+ class triangular_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ triangular_distribution(RealType lower = -1, RealType mode = 0) RealType upper = 1); // Constructor.
+ : m_lower(lower), m_mode(mode), m_upper(upper) // Default is -1, 0, +1 symmetric triangular distribution.
+ // Accessor functions.
+ RealType lower()const;
+ RealType mode()const;
+ RealType upper()const;
+ }; // class triangular_distribution
+
+ }} // namespaces
+
+The [@http://en.wikipedia.org/wiki/Triangular_distribution triangular distribution]
+is a [@http://en.wikipedia.org/wiki/Continuous_distribution continuous]
+[@http://en.wikipedia.org/wiki/Probability_distribution probability distribution]
+with a lower limit a,
+[@http://en.wikipedia.org/wiki/Mode_%28statistics%29 mode c],
+and upper limit b.
+
+The triangular distribution is often used where the distribution is only vaguely known,
+but, like the [@http://en.wikipedia.org/wiki/Uniform_distribution_%28continuous%29 uniform distribution],
+upper and limits are 'known', but a 'best guess', the mode or center point, is also added.
+It has been recommended as a
+[@http://www.worldscibooks.com/mathematics/etextbook/5720/5720_chap1.pdf proxy for the beta distribution.]
+The distribution is used in business decision making and project planning.
+
+The [@http://en.wikipedia.org/wiki/Triangular_distribution triangular distribution]
+is a distribution with the
+[@http://en.wikipedia.org/wiki/Probability_density_function probability density function]:
+
+__spaces f(x) =
+
+* 2(x-a)/(b-a) (c-a) for a <= x <= c
+
+* 2(b-x)/(b-a)(b-c) for c < x <= b
+
+Parameter ['a] (lower) can be any finite value.
+Parameter ['b] (upper) can be any finite value > a (lower).
+Parameter ['c] (mode) a <= c <= b. This is the most probable value.
+
+The [@http://en.wikipedia.org/wiki/Random_variate random variate] x must also be finite, and is supported lower <= x <= upper.
+
+The triangular distribution may be appropriate when an assumption of a normal distribution
+is unjustified because uncertainty is caused by rounding and quantization from analog to digital conversion.
+Upper and lower limits are known, and the most probable value lies midway.
+
+The distribution simplifies when the 'best guess' is either the lower or upper limit - a 90 degree angle triangle.
+The 001 triangular distribution which expresses an estimate that the lowest value is the most likely;
+for example, you believe that the next-day quoted delivery date is most likely
+(knowing that a quicker delivery is impossible - the postman only comes once a day),
+and that longer delays are decreasingly likely,
+and delivery is assumed to never take more than your upper limit.
+
+The following graph illustrates how the
+[@http://en.wikipedia.org/wiki/Probability_density_function probability density function PDF]
+varies with the various parameters:
+
+[graph triangular_pdf]
+
+and cumulative distribution function
+
+[graph triangular_cdf]
+
+[h4 Member Functions]
+
+ triangular_distribution(RealType lower = 0, RealType mode = 0 RealType upper = 1);
+
+Constructs a [@http://en.wikipedia.org/wiki/triangular_distribution triangular distribution]
+with lower /lower/ (a) and upper /upper/ (b).
+
+Requires that the /lower/, /mode/ and /upper/ parameters are all finite,
+otherwise calls __domain_error.
+
+[warning These constructors are slightly different from the analogs provided by __Mathworld
+[@http://reference.wolfram.com/language/ref/TriangularDistribution.html Triangular distribution],
+where
+
+[^TriangularDistribution\[{min, max}\]] represents a [*symmetric] triangular statistical distribution giving values between min and max.[br]
+[^TriangularDistribution\[\]] represents a [*symmetric] triangular statistical distribution giving values between 0 and 1.[br]
+[^TriangularDistribution\[{min, max}, c\]] represents a triangular distribution with mode at c (usually [*asymmetric]).[br]
+
+So, for example, to compute a variance using __WolframAlpha, use
+[^N\[variance\[TriangularDistribution{1, +2}\], 50\]]
+]
+
+The parameters of a distribution can be obtained using these member functions:
+
+ RealType lower()const;
+
+Returns the ['lower] parameter of this distribution (default -1).
+
+ RealType mode()const;
+
+Returns the ['mode] parameter of this distribution (default 0).
+
+ RealType upper()const;
+
+Returns the ['upper] parameter of this distribution (default+1).
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] that are generic to all
+distributions are supported: __usual_accessors.
+
+The domain of the random variable is \lower\ to \upper\,
+and the supported range is lower <= x <= upper.
+
+[h4 Accuracy]
+
+The triangular distribution is implemented with simple arithmetic operators and so should have errors within an epsilon or two,
+except quantiles with arguments nearing the extremes of zero and unity.
+
+[h4 Implementation]
+
+In the following table, a is the /lower/ parameter of the distribution,
+c is the /mode/ parameter,
+b is the /upper/ parameter,
+/x/ is the random variate, /p/ is the probability and /q = 1-p/.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Using the relation: pdf = 0 for x < mode, 2(x-a)\/(b-a)(c-a) else 2*(b-x)\/((b-a)(b-c))]]
+[[cdf][Using the relation: cdf = 0 for x < mode (x-a)[super 2]\/((b-a)(c-a)) else 1 - (b-x)[super 2]\/((b-a)(b-c))]]
+[[cdf complement][Using the relation: q = 1 - p ]]
+[[quantile][let p0 = (c-a)\/(b-a) the point of inflection on the cdf,
+then given probability p and q = 1-p:
+
+x = sqrt((b-a)(c-a)p) + a ; for p < p0
+
+x = c ; for p == p0
+
+x = b - sqrt((b-a)(b-c)q) ; for p > p0
+
+(See [@../../../../boost/math/distributions/triangular.hpp /boost/math/distributions/triangular.hpp] for details.)]]
+[[quantile from the complement][As quantile (See [@../../../../boost/math/distributions/triangular.hpp /boost/math/distributions/triangular.hpp] for details.)]]
+[[mean][(a + b + 3) \/ 3 ]]
+[[variance][(a[super 2]+b[super 2]+c[super 2] - ab - ac - bc)\/18]]
+[[mode][c]]
+[[skewness][(See [@../../../../boost/math/distributions/triangular.hpp /boost/math/distributions/triangular.hpp] for details). ]]
+[[kurtosis][12\/5]]
+[[kurtosis excess][-3\/5]]
+]
+
+Some 'known good' test values were obtained using __WolframAlpha.
+
+[h4 References]
+
+* [@http://en.wikipedia.org/wiki/Triangular_distribution Wikpedia triangular distribution]
+* [@http://mathworld.wolfram.com/TriangularDistribution.html Weisstein, Eric W. "Triangular Distribution." From MathWorld--A Wolfram Web Resource.]
+* Evans, M.; Hastings, N.; and Peacock, B. "Triangular Distribution." Ch. 40 in Statistical Distributions, 3rd ed. New York: Wiley, pp. 187-188, 2000, ISBN - 0471371246.
+* [@http://www.measurement.sk/2002/S1/Wimmer2.pdf Gejza Wimmer, Viktor Witkovsky and Tomas Duby,
+Measurement Science Review, Volume 2, Section 1, 2002, Proper Rounding Of The Measurement Results Under The Assumption Of Triangular Distribution.]
+
+[endsect][/section:triangular_dist triangular]
+
+[/
+ 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).
+]
+
diff --git a/doc/distributions/uniform.qbk b/doc/distributions/uniform.qbk
new file mode 100644
index 0000000..04e1e79
--- /dev/null
+++ b/doc/distributions/uniform.qbk
@@ -0,0 +1,134 @@
+[section:uniform_dist Uniform Distribution]
+
+
+``#include <boost/math/distributions/uniform.hpp>``
+
+ namespace boost{ namespace math{
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class uniform_distribution;
+
+ typedef uniform_distribution<> uniform;
+
+ template <class RealType, class ``__Policy``>
+ class uniform_distribution
+ {
+ public:
+ typedef RealType value_type;
+
+ uniform_distribution(RealType lower = 0, RealType upper = 1); // Constructor.
+ : m_lower(lower), m_upper(upper) // Default is standard uniform distribution.
+ // Accessor functions.
+ RealType lower()const;
+ RealType upper()const;
+ }; // class uniform_distribution
+
+ }} // namespaces
+
+The uniform distribution, also known as a rectangular distribution,
+is a probability distribution that has constant probability.
+
+The [@http://en.wikipedia.org/wiki/Uniform_distribution_%28continuous%29 continuous uniform distribution]
+is a distribution with the
+[@http://en.wikipedia.org/wiki/Probability_density_function probability density function]:
+
+f(x) =
+
+* 1 / (upper - lower) for lower < x < upper
+
+* zero for x < lower or x > upper
+
+and in this implementation:
+
+* 1 / (upper - lower) for x = lower or x = upper
+
+The choice of x = lower or x = upper is made because statistical use of this distribution judged is most likely:
+the method of maximum likelihood uses this definition.
+
+There is also a [@http://en.wikipedia.org/wiki/Discrete_uniform_distribution *discrete* uniform distribution].
+
+Parameters lower and upper can be any finite value.
+
+The [@http://en.wikipedia.org/wiki/Random_variate random variate]
+x must also be finite, and is supported lower <= x <= upper.
+
+The lower parameter is also called the
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm location parameter],
+[@http://en.wikipedia.org/wiki/Location_parameter that is where the origin of a plot will lie],
+and (upper - lower) is also called the [@http://en.wikipedia.org/wiki/Scale_parameter scale parameter].
+
+The following graph illustrates how the
+[@http://en.wikipedia.org/wiki/Probability_density_function probability density function PDF]
+varies with the shape parameter:
+
+[graph uniform_pdf]
+
+Likewise for the CDF:
+
+[graph uniform_cdf]
+
+[h4 Member Functions]
+
+ uniform_distribution(RealType lower = 0, RealType upper = 1);
+
+Constructs a [@http://en.wikipedia.org/wiki/uniform_distribution
+uniform distribution] with lower /lower/ (a) and upper /upper/ (b).
+
+Requires that the /lower/ and /upper/ parameters are both finite;
+otherwise if infinity or NaN then calls __domain_error.
+
+ RealType lower()const;
+
+Returns the /lower/ parameter of this distribution.
+
+ RealType upper()const;
+
+Returns the /upper/ parameter of this distribution.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
+that are generic to all distributions are supported: __usual_accessors.
+
+The domain of the random variable is any finite value,
+but the supported range is only /lower/ <= x <= /upper/.
+
+[h4 Accuracy]
+
+The uniform distribution is implemented with simple arithmetic operators and so should have errors within an epsilon or two.
+
+[h4 Implementation]
+
+In the following table a is the /lower/ parameter of the distribution,
+b is the /upper/ parameter,
+/x/ is the random variate, /p/ is the probability and /q = 1-p/.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Using the relation: pdf = 0 for x < a, 1 / (b - a) for a <= x <= b, 0 for x > b ]]
+[[cdf][Using the relation: cdf = 0 for x < a, (x - a) / (b - a) for a <= x <= b, 1 for x > b]]
+[[cdf complement][Using the relation: q = 1 - p, (b - x) / (b - a) ]]
+[[quantile][Using the relation: x = p * (b - a) + a; ]]
+[[quantile from the complement][x = -q * (b - a) + b ]]
+[[mean][(a + b) / 2 ]]
+[[variance][(b - a) [super 2] / 12 ]]
+[[mode][any value in \[a, b\] but a is chosen. (Would NaN be better?) ]]
+[[skewness][0]]
+[[kurtosis excess][-6/5 = -1.2 exactly. (kurtosis - 3)]]
+[[kurtosis][9/5]]
+]
+
+[h4 References]
+* [@http://en.wikipedia.org/wiki/Uniform_distribution_%28continuous%29 Wikpedia continuous uniform distribution]
+* [@http://mathworld.wolfram.com/UniformDistribution.html Weisstein, Weisstein, Eric W. "Uniform Distribution." From MathWorld--A Wolfram Web Resource.]
+* [@http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm]
+
+[endsect][/section:uniform_dist Uniform]
+
+[/
+ 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).
+]
+
diff --git a/doc/distributions/weibull.qbk b/doc/distributions/weibull.qbk
new file mode 100644
index 0000000..0d57776
--- /dev/null
+++ b/doc/distributions/weibull.qbk
@@ -0,0 +1,132 @@
+[section:weibull_dist Weibull Distribution]
+
+
+``#include <boost/math/distributions/weibull.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class ``__Policy`` = ``__policy_class`` >
+ class weibull_distribution;
+
+ typedef weibull_distribution<> weibull;
+
+ template <class RealType, class ``__Policy``>
+ class weibull_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+ // Construct:
+ weibull_distribution(RealType shape, RealType scale = 1)
+ // Accessors:
+ RealType shape()const;
+ RealType scale()const;
+ };
+
+ }} // namespaces
+
+The [@http://en.wikipedia.org/wiki/Weibull_distribution Weibull distribution]
+is a continuous distribution
+with the
+[@http://en.wikipedia.org/wiki/Probability_density_function probability density function]:
+
+f(x; [alpha], [beta]) = ([alpha]\/[beta]) * (x \/ [beta])[super [alpha] - 1] * e[super -(x\/[beta])[super [alpha]]]
+
+For shape parameter [alpha][space] > 0, and scale parameter [beta][space] > 0, and x > 0.
+
+The Weibull distribution is often used in the field of failure analysis;
+in particular it can mimic distributions where the failure rate varies over time.
+If the failure rate is:
+
+* constant over time, then [alpha][space] = 1, suggests that items are failing from random events.
+* decreases over time, then [alpha][space] < 1, suggesting "infant mortality".
+* increases over time, then [alpha][space] > 1, suggesting "wear out" - more likely to fail as time goes by.
+
+The following graph illustrates how the PDF varies with the shape parameter [alpha]:
+
+[graph weibull_pdf1]
+
+While this graph illustrates how the PDF varies with the scale parameter [beta]:
+
+[graph weibull_pdf2]
+
+[h4 Related distributions]
+
+When [alpha][space] = 3, the
+[@http://en.wikipedia.org/wiki/Weibull_distribution Weibull distribution] appears similar to the
+[@http://en.wikipedia.org/wiki/Normal_distribution normal distribution].
+When [alpha][space] = 1, the Weibull distribution reduces to the
+[@http://en.wikipedia.org/wiki/Exponential_distribution exponential distribution].
+The relationship of the types of extreme value distributions, of which the Weibull is but one, is
+discussed by
+[@http://www.worldscibooks.com/mathematics/p191.html Extreme Value Distributions, Theory and Applications
+Samuel Kotz & Saralees Nadarajah].
+
+
+[h4 Member Functions]
+
+ weibull_distribution(RealType shape, RealType scale = 1);
+
+Constructs a [@http://en.wikipedia.org/wiki/Weibull_distribution
+Weibull distribution] with shape /shape/ and scale /scale/.
+
+Requires that the /shape/ and /scale/ parameters are both greater than zero,
+otherwise calls __domain_error.
+
+ RealType shape()const;
+
+Returns the /shape/ parameter of this distribution.
+
+ RealType scale()const;
+
+Returns the /scale/ parameter of this distribution.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] that are generic to all
+distributions are supported: __usual_accessors.
+
+The domain of the random variable is \[0, [infin]\].
+
+[h4 Accuracy]
+
+The Weibull distribution is implemented in terms of the
+standard library `log` and `exp` functions plus __expm1 and __log1p
+and as such should have very low error rates.
+
+[h4 Implementation]
+
+
+In the following table [alpha][space] is the shape parameter of the distribution,
+[beta][space] is its scale parameter, /x/ is the random variate, /p/ is the probability
+and /q = 1-p/.
+
+[table
+[[Function][Implementation Notes]]
+[[pdf][Using the relation: pdf = [alpha][beta][super -[alpha] ]x[super [alpha] - 1] e[super -(x/beta)[super alpha]] ]]
+[[cdf][Using the relation: p = -__expm1(-(x\/[beta])[super [alpha]]) ]]
+[[cdf complement][Using the relation: q = e[super -(x\/[beta])[super [alpha]]] ]]
+[[quantile][Using the relation: x = [beta] * (-__log1p(-p))[super 1\/[alpha]] ]]
+[[quantile from the complement][Using the relation: x = [beta] * (-log(q))[super 1\/[alpha]] ]]
+[[mean][[beta] * [Gamma](1 + 1\/[alpha]) ]]
+[[variance][[beta][super 2]([Gamma](1 + 2\/[alpha]) - [Gamma][super 2](1 + 1\/[alpha])) ]]
+[[mode][[beta](([alpha] - 1) \/ [alpha])[super 1\/[alpha]] ]]
+[[skewness][Refer to [@http://mathworld.wolfram.com/WeibullDistribution.html Weisstein, Eric W. "Weibull Distribution." From MathWorld--A Wolfram Web Resource.] ]]
+[[kurtosis][Refer to [@http://mathworld.wolfram.com/WeibullDistribution.html Weisstein, Eric W. "Weibull Distribution." From MathWorld--A Wolfram Web Resource.] ]]
+[[kurtosis excess][Refer to [@http://mathworld.wolfram.com/WeibullDistribution.html Weisstein, Eric W. "Weibull Distribution." From MathWorld--A Wolfram Web Resource.] ]]
+]
+
+[h4 References]
+* [@http://en.wikipedia.org/wiki/Weibull_distribution ]
+* [@http://mathworld.wolfram.com/WeibullDistribution.html Weisstein, Eric W. "Weibull Distribution." From MathWorld--A Wolfram Web Resource.]
+* [@http://www.itl.nist.gov/div898/handbook/eda/section3/eda3668.htm Weibull in NIST Exploratory Data Analysis]
+
+[endsect][/section:weibull Weibull]
+
+[/
+ 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).
+]