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

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