ceph/src/boost/libs/math/doc/distributions/non_members.qbk

   1 [section:nmp Non-Member Properties]
   2
   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.
  11
  12 [h4:function_index Function Index]
  13
  14 * __cdf.
  15 * __ccdf.
  16 * __chf.
  17 * __hazard.
  18 * __kurtosis.
  19 * __kurtosis_excess
  20 * __mean.
  21 * __median.
  22 * __mode.
  23 * __pdf.
  24 * __range.
  25 * __quantile.
  26 * __quantile_c.
  27 * __skewness.
  28 * __sd.
  29 * __support.
  30 * __variance.
  31
  32 [h4:concept_index Conceptual Index]
  33
  34 * __ccdf.
  35 * __cdf.
  36 * __chf.
  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].
  39 * __hazard
  40 * [link math_toolkit.dist_ref.nmp.lower_critical Lower Critical Value].
  41 * __kurtosis.
  42 * __kurtosis_excess
  43 * __mean.
  44 * __median.
  45 * __mode.
  46 * [link math_toolkit.dist_ref.nmp.cdfPQ P].
  47 * [link math_toolkit.dist_ref.nmp.percent Percent Point Function].
  48 * __pdf.
  49 * [link math_toolkit.dist_ref.nmp.pmf Probability Mass Function].
  50 * __range.
  51 * [link math_toolkit.dist_ref.nmp.cdfPQ Q].
  52 * __quantile.
  53 * [link math_toolkit.dist_ref.nmp.quantile_c Quantile from the complement of the probability].
  54 * __skewness.
  55 * __sd
  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].
  59 * __variance.
  60
  61 [h4:cdf Cumulative Distribution Function]
  62
  63    template <class RealType, class ``__Policy``>
  64    RealType cdf(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist, const RealType& x);
  65
  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.
  69
  70 This function may return a __domain_error if the random variable is outside
  71 the defined range for the distribution.
  72
  73 For example, the following graph shows the cdf for the
  74 normal distribution:
  75
  76 [$../graphs/cdf.png]
  77
  78 [h4:ccdf Complement of the Cumulative Distribution Function]
  79
  80    template <class Distribution, class RealType>
  81    RealType cdf(const ``['Unspecified-Complement-Type]``<Distribution, RealType>& comp);
  82
  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.
  87
  88 This is also known as the survival function.
  89
  90 This function may return a __domain_error if the random variable is outside
  91 the defined range for the distribution.
  92
  93 In this library, it is obtained by wrapping the arguments to the `cdf`
  94 function in a call to `complement`, for example:
  95
  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;
 100
 101 For example, the following graph shows the __complement of the cdf for the
 102 normal distribution:
 103
 104 [$../graphs/survival.png]
 105
 106 See __why_complements for why the complement is useful and when it should be used.
 107
 108 [h4:hazard Hazard Function]
 109
 110    template <class RealType, class ``__Policy``>
 111    RealType hazard(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist, const RealType& x);
 112
 113 Returns the __hazard of /x/ and distibution /dist/.
 114
 115 This function may return a __domain_error if the random variable is outside
 116 the defined range for the distribution.
 117
 118 [equation hazard]
 119
 120 [caution
 121 Some authors refer to this as the conditional failure
 122 density function rather than the hazard function.]
 123
 124 [h4:chf Cumulative Hazard Function]
 125
 126    template <class RealType, class ``__Policy``>
 127    RealType chf(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist, const RealType& x);
 128
 129 Returns the __chf of /x/ and distibution /dist/.
 130
 131 This function may return a __domain_error if the random variable is outside
 132 the defined range for the distribution.
 133
 134 [equation chf]
 135
 136 [caution
 137 Some authors refer to this as simply the "Hazard Function".]
 138
 139 [h4:mean mean]
 140
 141    template<class RealType, class ``__Policy``>
 142    RealType mean(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
 143
 144 Returns the mean of the distribution /dist/.
 145
 146 This function may return a __domain_error if the distribution does not have
 147 a defined mean (for example the Cauchy distribution).
 148
 149 [h4:median median]
 150
 151    template<class RealType, class ``__Policy``>
 152    RealType median(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
 153
 154 Returns the median of the distribution /dist/.
 155
 156 [h4:mode mode]
 157
 158    template<class RealType, ``__Policy``>
 159    RealType mode(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
 160
 161 Returns the mode of the distribution /dist/.
 162
 163 This function may return a __domain_error if the distribution does not have
 164 a defined mode.
 165
 166 [h4:pdf Probability Density Function]
 167
 168    template <class RealType, class ``__Policy``>
 169    RealType pdf(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist, const RealType& x);
 170
 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:
 175 see the __cdf.
 176
 177 For a discrete distribution, the pdf is the probability that the
 178 variate takes the value x.
 179
 180 This function may return a __domain_error if the random variable is outside
 181 the defined range for the distribution.
 182
 183 For example, for a standard normal distribution the pdf looks like this:
 184
 185 [$../graphs/pdf.png]
 186
 187 [h4:range Range]
 188
 189    template<class RealType, class ``__Policy``>
 190    std::pair<RealType, RealType> range(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
 191
 192 Returns the valid range of the random variable over distribution /dist/.
 193
 194 [h4:quantile Quantile]
 195
 196    template <class RealType, class ``__Policy``>
 197    RealType quantile(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist, const RealType& p);
 198
 199 The quantile is best viewed as the inverse of the __cdf, it returns
 200 a value /x/ such that `cdf(dist, x) == p`.
 201
 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.
 204
 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.
 208
 209 The following graph shows the quantile function for a standard normal
 210 distribution:
 211
 212 [$../graphs/quantile.png]
 213
 214 [h4:quantile_c Quantile from the complement of the probability.]
 215 See also [link math_toolkit.stat_tut.overview.complements complements].
 216
 217
 218    template <class Distribution, class RealType>
 219    RealType quantile(const ``['Unspecified-Complement-Type]``<Distribution, RealType>& comp);
 220
 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:
 224
 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;
 230
 231 The function computes a value /x/ such that
 232 `cdf(complement(dist, x)) == q` where /q/ is complement of the
 233 probability.
 234
 235 [link why_complements Why complements?]
 236
 237 This function is also called the inverse survival function, and is the
 238 same as calculating the ['upper critical value] of a distribution.
 239
 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.
 243
 244 The following graph show the inverse survival function for the normal
 245 distribution:
 246
 247 [$../graphs/survival_inv.png]
 248
 249 [h4:sd Standard Deviation]
 250
 251    template <class RealType, class ``__Policy``>
 252    RealType standard_deviation(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
 253
 254 Returns the standard deviation of distribution /dist/.
 255
 256 This function may return a __domain_error if the distribution does not have
 257 a defined standard deviation.
 258
 259 [h4:support support]
 260
 261    template<class RealType, class ``__Policy``>
 262    std::pair<RealType, RealType> support(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
 263
 264 Returns the supported range of random variable over the distribution /dist/.
 265
 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.
 272
 273 [h4:variance Variance]
 274
 275    template <class RealType, class ``__Policy``>
 276    RealType variance(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
 277
 278 Returns the variance of the distribution /dist/.
 279
 280 This function may return a __domain_error if the distribution does not have
 281 a defined variance.
 282
 283 [h4:skewness Skewness]
 284
 285    template <class RealType, class ``__Policy``>
 286    RealType skewness(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
 287
 288 Returns the skewness of the distribution /dist/.
 289
 290 This function may return a __domain_error if the distribution does not have
 291 a defined skewness.
 292
 293 [h4:kurtosis Kurtosis]
 294
 295    template <class RealType, class ``__Policy``>
 296    RealType kurtosis(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
 297
 298 Returns the 'proper' kurtosis (normalized fourth moment) of the distribution /dist/.
 299
 300 kertosis = [beta][sub 2][space]= [mu][sub 4][space] / [mu][sub 2][super 2]
 301
 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.
 304
 305 The kurtosis is a measure of the "peakedness" of a distribution.
 306
 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.
 314
 315   kurtosis_excess = 'proper' kurtosis - 3
 316
 317 This subtraction of 3 is convenient so that the ['kurtosis excess]
 318 of a normal distribution is zero.
 319
 320 This function may return a __domain_error if the distribution does not have
 321 a defined kurtosis.
 322
 323 'Proper' kurtosis can have a value from zero to + infinity.
 324
 325 [h4:kurtosis_excess Kurtosis excess]
 326
 327    template <class RealType, ``__Policy``>
 328    RealType kurtosis_excess(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist);
 329
 330 Returns the kurtosis excess of the distribution /dist/.
 331
 332 kurtosis excess = [gamma][sub 2][space]= [mu][sub 4][space] / [mu][sub 2][super 2][space]- 3 = kurtosis - 3
 333
 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.
 336
 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.
 340
 341 This function may return a __domain_error if the distribution does not have
 342 a defined kurtosis excess.
 343
 344 Kurtosis excess can have a value from -2 to + infinity.
 345
 346   kurtosis = kurtosis_excess +3;
 347
 348 The kurtosis excess of a normal distribution is zero.
 349
 350 [h4:cdfPQ P and Q]
 351
 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
 355 by these functions.
 356
 357 [h4:percent Percent Point Function or Percentile]
 358
 359 The percent point function, also known as the percentile, is the same as
 360 the __quantile.
 361
 362 [h4:cdf_inv Inverse CDF Function.]
 363
 364 The inverse of the cumulative distribution function, is the same as the
 365 __quantile.
 366
 367 [h4:survival_inv Inverse Survival Function.]
 368
 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].
 372
 373 [h4:pmf Probability Mass Function]
 374
 375 The Probability Mass Function is the same as the __pdf.
 376
 377 The term Mass Function is usually applied to discrete distributions,
 378 while the term __pdf applies to continuous distributions.
 379
 380 [h4:lower_critical Lower Critical Value.]
 381
 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.
 385
 386 [h4: upper_critical Upper Critical Value.]
 387
 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
 391 probability].
 392
 393 [h4:survival Survival Function]
 394
 395 Refer to the __ccdf.
 396
 397 [endsect][/section:nmp Non-Member Properties]
 398
 399
 400 [/ non_members.qbk
 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).
 405 ]
 406