...one of the most highly
regarded and expertly designed C++ library projects in the
world.

— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards

This is the documentation for a snapshot of the develop branch, built from commit 749d228efa.

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 concept index to find the property you want by the name you are most familiar with. Or use the function index to go straight to the function you want if you already know its name.

- Cumulative Distribution Function.
- Complement of the Cumulative Distribution Function.
- Cumulative Hazard Function.
- Hazard Function.
- kurtosis.
- kurtosis_excess
- mean.
- median.
- mode.
- Probability Density Function.
- range.
- Quantile.
- Quantile from the complement of the probability.
- skewness.
- standard deviation.
- support.
- variance.
- entropy.

- Complement of the Cumulative Distribution Function.
- Cumulative Distribution Function.
- Cumulative Hazard Function.
- Inverse Cumulative Distribution Function.
- Inverse Survival Function.
- Hazard Function
- Lower Critical Value.
- kurtosis.
- kurtosis_excess
- mean.
- median.
- mode.
- P.
- Percent Point Function.
- Probability Density Function.
- Probability Mass Function.
- range.
- Q.
- Quantile.
- Quantile from the complement of the probability.
- skewness.
- standard deviation
- Survival Function.
- support.
- Upper Critical Value.
- variance.
- entropy

template <class RealType, class Policy> RealType cdf(constDistribution-Type<RealType, Policy>& dist, const RealType& x);

The Cumulative Distribution Function 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 Probability Density Function.

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:

template <class Distribution, class RealType> RealType cdf(constUnspecified-Complement-Type<Distribution, RealType>& comp);

The complement of the Cumulative Distribution Function is the probability that the variable takes a value greater than x. It is equivalent to the integral from x to infinity of the Probability Density Function, or 1 minus the Cumulative Distribution Function 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:

See why complements? for why the complement is useful and when it should be used.

template <class RealType, class Policy> RealType hazard(constDistribution-Type<RealType, Policy>& dist, const RealType& x);

Returns the Hazard Function
of *x* and distribution *dist*.

This function may return a domain_error if the random variable is outside the defined range for the distribution.

Caution | |
---|---|

Some authors refer to this as the conditional failure density function rather than the hazard function. |

template <class RealType, class Policy> RealType chf(constDistribution-Type<RealType, Policy>& dist, const RealType& x);

Returns the Cumulative Hazard
Function of *x* and distribution *dist*.

Caution | |
---|---|

Some authors refer to this as simply the "Hazard Function". |

template<class RealType, class Policy> RealType mean(constDistribution-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).

template<class RealType, class Policy> RealType median(constDistribution-Type<RealType, Policy>& dist);

Returns the median of the distribution *dist*.

template<class RealType, Policy> RealType mode(constDistribution-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.

template <class RealType, class Policy> RealType pdf(constDistribution-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 Cumulative Distribution Function.

For a discrete distribution, the pdf is the probability that the variate takes the value x.

For example, for a standard normal distribution the pdf looks like this:

template<class RealType, class Policy> std::pair<RealType, RealType> range(constDistribution-Type<RealType, Policy>& dist);

Returns the valid range of the random variable over distribution *dist*.

template <class RealType, class Policy> RealType quantile(constDistribution-Type<RealType, Policy>& dist, const RealType& p);

The quantile is best viewed as the inverse of the Cumulative
Distribution Function, 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:

See also complements.

template <class Distribution, class RealType> RealType quantile(constUnspecified-Complement-Type<Distribution, RealType>& comp);

This is the inverse of the Complement
of the Cumulative Distribution Function. 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.

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 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 show the inverse survival function for the normal distribution:

template <class RealType, class Policy> RealType standard_deviation(constDistribution-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.

template<class RealType, class Policy> std::pair<RealType, RealType> support(constDistribution-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 "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.

template <class RealType, class Policy> RealType variance(constDistribution-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.

template <class RealType, class Policy> RealType skewness(constDistribution-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.

template <class RealType, class Policy> RealType kurtosis(constDistribution-Type<RealType, Policy>& dist);

Returns the 'proper' kurtosis (normalized fourth moment) of the distribution
*dist*.

kurtosis = β_{2}= μ_{4} / μ_{2}^{2}

Where μ_{i} is the i'th central moment of the distribution, and in particular
μ_{2} 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 Wolfram MathWorld (that includes a table of formulae for kurtosis excess for various distributions) but NOT the definition of 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.

template <class RealType, Policy> RealType kurtosis_excess(constDistribution-Type<RealType, Policy>& dist);

Returns the kurtosis excess of the distribution *dist*.

kurtosis excess = γ_{2}= μ_{4} / μ_{2}^{2}- 3 = kurtosis - 3

Where μ_{i} is the i'th central moment of the distribution, and in particular
μ_{2} 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.

The terms P and Q are sometimes used to refer to the Cumulative Distribution Function and its complement respectively. Lowercase p and q are sometimes used to refer to the values returned by these functions.

The percent point function, also known as the percentile, is the same as the Quantile.

The inverse of the cumulative distribution function, is the same as the Quantile.

The inverse of the survival function, is the same as computing the quantile from the complement of the probability.

The Probability Mass Function is the same as the Probability Density Function.

The term Mass Function is usually applied to discrete distributions, while the term Probability Density Function applies to continuous distributions.

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.

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 quantile from the complement of the probability.

Refer to the Complement of the Cumulative Distribution Function.

The entropy (or differential entropy) of a continuous probability distribution
*p* is defined as

Note that the "natural" properties of the differential entropy
do not uniquely specify a log base. In the Boost library, we *always*
use the natural logarithm to compute differential entropy. This choice of
log base for entropy is sometimes referred to as "entropy measured in
nats". See On
the entropy of continuous probability distributions for more information.