1 [section:nmp Non-Member Properties]
3 Properties that are common to all distributions are accessed via non-member
4 getter functions: non-membership allows more of these functions to be added over time,
5 as the need arises. Unfortunately the literature uses many different and
6 confusing names to refer to a rather small number of actual concepts; refer
7 to the [link math_toolkit.dist_ref.nmp.concept_index concept index] to find the property you
8 want by the name you are most familiar with.
9 Or use the [link math_toolkit.dist_ref.nmp.function_index function index]
10 to go straight to the function you want if you already know its name.
12 [h4:function_index Function Index]
32 [h4:concept_index Conceptual Index]
37 * [link math_toolkit.dist_ref.nmp.cdf_inv Inverse Cumulative Distribution Function].
38 * [link math_toolkit.dist_ref.nmp.survival_inv Inverse Survival Function].
40 * [link math_toolkit.dist_ref.nmp.lower_critical Lower Critical Value].
46 * [link math_toolkit.dist_ref.nmp.cdfPQ P].
47 * [link math_toolkit.dist_ref.nmp.percent Percent Point Function].
49 * [link math_toolkit.dist_ref.nmp.pmf Probability Mass Function].
51 * [link math_toolkit.dist_ref.nmp.cdfPQ Q].
53 * [link math_toolkit.dist_ref.nmp.quantile_c Quantile from the complement of the probability].
56 * [link math_toolkit.dist_ref.nmp.survival Survival Function].
57 * [link math_toolkit.dist_ref.nmp.support support].
58 * [link math_toolkit.dist_ref.nmp.upper_critical Upper Critical Value].
61 [h4:cdf Cumulative Distribution Function]
63 template <class RealType, class ``__Policy``>
64 RealType cdf(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist, const RealType& x);
66 The __cdf is the probability that
67 the variable takes a value less than or equal to x. It is equivalent
68 to the integral from -infinity to x of the __pdf.
70 This function may return a __domain_error if the random variable is outside
71 the defined range for the distribution.
73 For example, the following graph shows the cdf for the
78 [h4:ccdf Complement of the Cumulative Distribution Function]
80 template <class Distribution, class RealType>
81 RealType cdf(const ``['Unspecified-Complement-Type]``<Distribution, RealType>& comp);
83 The complement of the __cdf
84 is the probability that
85 the variable takes a value greater than x. It is equivalent
86 to the integral from x to infinity of the __pdf, or 1 minus the __cdf of x.
88 This is also known as the survival function.
90 This function may return a __domain_error if the random variable is outside
91 the defined range for the distribution.
93 In this library, it is obtained by wrapping the arguments to the `cdf`
94 function in a call to `complement`, for example:
96 // standard normal distribution object:
97 boost::math::normal norm;
98 // print survival function for x=2.0:
99 std::cout << cdf(complement(norm, 2.0)) << std::endl;
101 For example, the following graph shows the __complement of the cdf for the
104 [$../graphs/survival.png]
106 See __why_complements for why the complement is useful and when it should be used.
108 [h4:hazard Hazard Function]
110 template <class RealType, class ``__Policy``>
111 RealType hazard(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist, const RealType& x);
113 Returns the __hazard of /x/ and distibution /dist/.
115 This function may return a __domain_error if the random variable is outside
116 the defined range for the distribution.
121 Some authors refer to this as the conditional failure
122 density function rather than the hazard function.]
124 [h4:chf Cumulative Hazard Function]
126 template <class RealType, class ``__Policy``>
127 RealType chf(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist, const RealType& x);
129 Returns the __chf of /x/ and distibution /dist/.
131 This function may return a __domain_error if the random variable is outside
132 the defined range for the distribution.
137 Some authors refer to this as simply the "Hazard Function".]
141 template<class RealType, class ``__Policy``>
142 RealType mean(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
144 Returns the mean of the distribution /dist/.
146 This function may return a __domain_error if the distribution does not have
147 a defined mean (for example the Cauchy distribution).
151 template<class RealType, class ``__Policy``>
152 RealType median(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
154 Returns the median of the distribution /dist/.
158 template<class RealType, ``__Policy``>
159 RealType mode(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
161 Returns the mode of the distribution /dist/.
163 This function may return a __domain_error if the distribution does not have
166 [h4:pdf Probability Density Function]
168 template <class RealType, class ``__Policy``>
169 RealType pdf(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist, const RealType& x);
171 For a continuous function, the probability density function (pdf) returns
172 the probability that the variate has the value x.
173 Since for continuous distributions the probability at a single point is actually zero,
174 the probability is better expressed as the integral of the pdf between two points:
177 For a discrete distribution, the pdf is the probability that the
178 variate takes the value x.
180 This function may return a __domain_error if the random variable is outside
181 the defined range for the distribution.
183 For example, for a standard normal distribution the pdf looks like this:
189 template<class RealType, class ``__Policy``>
190 std::pair<RealType, RealType> range(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
192 Returns the valid range of the random variable over distribution /dist/.
194 [h4:quantile Quantile]
196 template <class RealType, class ``__Policy``>
197 RealType quantile(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist, const RealType& p);
199 The quantile is best viewed as the inverse of the __cdf, it returns
200 a value /x/ such that `cdf(dist, x) == p`.
202 This is also known as the /percent point function/, or /percentile/, or /fractile/,
203 it is also the same as calculating the ['lower critical value] of a distribution.
205 This function returns a __domain_error if the probability lies outside [0,1].
206 The function may return an __overflow_error if there is no finite value
207 that has the specified probability.
209 The following graph shows the quantile function for a standard normal
212 [$../graphs/quantile.png]
214 [h4:quantile_c Quantile from the complement of the probability.]
215 See also [link math_toolkit.stat_tut.overview.complements complements].
218 template <class Distribution, class RealType>
219 RealType quantile(const ``['Unspecified-Complement-Type]``<Distribution, RealType>& comp);
221 This is the inverse of the __ccdf. It is calculated by wrapping
222 the arguments in a call to the quantile function in a call to
223 /complement/. For example:
225 // define a standard normal distribution:
226 boost::math::normal norm;
227 // print the value of x for which the complement
228 // of the probability is 0.05:
229 std::cout << quantile(complement(norm, 0.05)) << std::endl;
231 The function computes a value /x/ such that
232 `cdf(complement(dist, x)) == q` where /q/ is complement of the
235 [link why_complements Why complements?]
237 This function is also called the inverse survival function, and is the
238 same as calculating the ['upper critical value] of a distribution.
240 This function returns a __domain_error if the probablity lies outside [0,1].
241 The function may return an __overflow_error if there is no finite value
242 that has the specified probability.
244 The following graph show the inverse survival function for the normal
247 [$../graphs/survival_inv.png]
249 [h4:sd Standard Deviation]
251 template <class RealType, class ``__Policy``>
252 RealType standard_deviation(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
254 Returns the standard deviation of distribution /dist/.
256 This function may return a __domain_error if the distribution does not have
257 a defined standard deviation.
261 template<class RealType, class ``__Policy``>
262 std::pair<RealType, RealType> support(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
264 Returns the supported range of random variable over the distribution /dist/.
266 The distribution is said to be 'supported' over a range that is
267 [@http://en.wikipedia.org/wiki/Probability_distribution
268 "the smallest closed set whose complement has probability zero"].
269 Non-mathematicians might say it means the 'interesting' smallest range
270 of random variate x that has the cdf going from zero to unity.
271 Outside are uninteresting zones where the pdf is zero, and the cdf zero or unity.
273 [h4:variance Variance]
275 template <class RealType, class ``__Policy``>
276 RealType variance(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
278 Returns the variance of the distribution /dist/.
280 This function may return a __domain_error if the distribution does not have
283 [h4:skewness Skewness]
285 template <class RealType, class ``__Policy``>
286 RealType skewness(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
288 Returns the skewness of the distribution /dist/.
290 This function may return a __domain_error if the distribution does not have
293 [h4:kurtosis Kurtosis]
295 template <class RealType, class ``__Policy``>
296 RealType kurtosis(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
298 Returns the 'proper' kurtosis (normalized fourth moment) of the distribution /dist/.
300 kertosis = [beta][sub 2][space]= [mu][sub 4][space] / [mu][sub 2][super 2]
302 Where [mu][sub i][space] is the i'th central moment of the distribution, and
303 in particular [mu][sub 2][space] is the variance of the distribution.
305 The kurtosis is a measure of the "peakedness" of a distribution.
307 Note that the literature definition of kurtosis is confusing.
308 The definition used here is that used by for example
309 [@http://mathworld.wolfram.com/Kurtosis.html Wolfram MathWorld]
310 (that includes a table of formulae for kurtosis excess for various distributions)
311 but NOT the definition of
312 [@http://en.wikipedia.org/wiki/Kurtosis kurtosis used by Wikipedia]
313 which treats "kurtosis" and "kurtosis excess" as the same quantity.
315 kurtosis_excess = 'proper' kurtosis - 3
317 This subtraction of 3 is convenient so that the ['kurtosis excess]
318 of a normal distribution is zero.
320 This function may return a __domain_error if the distribution does not have
323 'Proper' kurtosis can have a value from zero to + infinity.
325 [h4:kurtosis_excess Kurtosis excess]
327 template <class RealType, ``__Policy``>
328 RealType kurtosis_excess(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
330 Returns the kurtosis excess of the distribution /dist/.
332 kurtosis excess = [gamma][sub 2][space]= [mu][sub 4][space] / [mu][sub 2][super 2][space]- 3 = kurtosis - 3
334 Where [mu][sub i][space] is the i'th central moment of the distribution, and
335 in particular [mu][sub 2][space] is the variance of the distribution.
337 The kurtosis excess is a measure of the "peakedness" of a distribution, and
338 is more widely used than the "kurtosis proper". It is defined so that
339 the kurtosis excess of a normal distribution is zero.
341 This function may return a __domain_error if the distribution does not have
342 a defined kurtosis excess.
344 Kurtosis excess can have a value from -2 to + infinity.
346 kurtosis = kurtosis_excess +3;
348 The kurtosis excess of a normal distribution is zero.
352 The terms P and Q are sometimes used to refer to the __cdf
353 and its [link math_toolkit.dist_ref.nmp.ccdf complement] respectively.
354 Lowercase p and q are sometimes used to refer to the values returned
357 [h4:percent Percent Point Function or Percentile]
359 The percent point function, also known as the percentile, is the same as
362 [h4:cdf_inv Inverse CDF Function.]
364 The inverse of the cumulative distribution function, is the same as the
367 [h4:survival_inv Inverse Survival Function.]
369 The inverse of the survival function, is the same as computing the
370 [link math_toolkit.dist_ref.nmp.quantile_c quantile
371 from the complement of the probability].
373 [h4:pmf Probability Mass Function]
375 The Probability Mass Function is the same as the __pdf.
377 The term Mass Function is usually applied to discrete distributions,
378 while the term __pdf applies to continuous distributions.
380 [h4:lower_critical Lower Critical Value.]
382 The lower critical value calculates the value of the random variable
383 given the area under the left tail of the distribution.
384 It is equivalent to calculating the __quantile.
386 [h4: upper_critical Upper Critical Value.]
388 The upper critical value calculates the value of the random variable
389 given the area under the right tail of the distribution. It is equivalent to
390 calculating the [link math_toolkit.dist_ref.nmp.quantile_c quantile from the complement of the
393 [h4:survival Survival Function]
397 [endsect][/section:nmp Non-Member Properties]
401 Copyright 2006 John Maddock and Paul A. Bristow.
402 Distributed under the Boost Software License, Version 1.0.
403 (See accompanying file LICENSE_1_0.txt or copy at
404 http://www.boost.org/LICENSE_1_0.txt).