WSJT-X/boost/libs/math/doc/distributions/non_members.qbk

407 lines
14 KiB
Plaintext

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