1[section:nmp Non-Member Properties] 2 3Properties that are common to all distributions are accessed via non-member 4getter functions: non-membership allows more of these functions to be added over time, 5as the need arises. Unfortunately the literature uses many different and 6confusing names to refer to a rather small number of actual concepts; refer 7to the [link math_toolkit.dist_ref.nmp.concept_index concept index] to find the property you 8want by the name you are most familiar with. 9Or use the [link math_toolkit.dist_ref.nmp.function_index function index] 10to 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* entropy. 32 33[h4:concept_index Conceptual Index] 34 35* __ccdf. 36* __cdf. 37* __chf. 38* [link math_toolkit.dist_ref.nmp.cdf_inv Inverse Cumulative Distribution Function]. 39* [link math_toolkit.dist_ref.nmp.survival_inv Inverse Survival Function]. 40* __hazard 41* [link math_toolkit.dist_ref.nmp.lower_critical Lower Critical Value]. 42* __kurtosis. 43* __kurtosis_excess 44* __mean. 45* __median. 46* __mode. 47* [link math_toolkit.dist_ref.nmp.cdfPQ P]. 48* [link math_toolkit.dist_ref.nmp.percent Percent Point Function]. 49* __pdf. 50* [link math_toolkit.dist_ref.nmp.pmf Probability Mass Function]. 51* __range. 52* [link math_toolkit.dist_ref.nmp.cdfPQ Q]. 53* __quantile. 54* [link math_toolkit.dist_ref.nmp.quantile_c Quantile from the complement of the probability]. 55* __skewness. 56* __sd 57* [link math_toolkit.dist_ref.nmp.survival Survival Function]. 58* [link math_toolkit.dist_ref.nmp.support support]. 59* [link math_toolkit.dist_ref.nmp.upper_critical Upper Critical Value]. 60* __variance. 61* entropy 62 63[h4:cdf Cumulative Distribution Function] 64 65 template <class RealType, class ``__Policy``> 66 RealType cdf(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist, const RealType& x); 67 68The __cdf is the probability that 69the variable takes a value less than or equal to x. It is equivalent 70to the integral from -infinity to x of the __pdf. 71 72This function may return a __domain_error if the random variable is outside 73the defined range for the distribution. 74 75For example, the following graph shows the cdf for the 76normal distribution: 77 78[$../graphs/cdf.png] 79 80[h4:ccdf Complement of the Cumulative Distribution Function] 81 82 template <class Distribution, class RealType> 83 RealType cdf(const ``['Unspecified-Complement-Type]``<Distribution, RealType>& comp); 84 85The complement of the __cdf 86is the probability that 87the variable takes a value greater than x. It is equivalent 88to the integral from x to infinity of the __pdf, or 1 minus the __cdf of x. 89 90This is also known as the survival function. 91 92This function may return a __domain_error if the random variable is outside 93the defined range for the distribution. 94 95In this library, it is obtained by wrapping the arguments to the `cdf` 96function in a call to `complement`, for example: 97 98 // standard normal distribution object: 99 boost::math::normal norm; 100 // print survival function for x=2.0: 101 std::cout << cdf(complement(norm, 2.0)) << std::endl; 102 103For example, the following graph shows the __complement of the cdf for the 104normal distribution: 105 106[$../graphs/survival.png] 107 108See __why_complements for why the complement is useful and when it should be used. 109 110[h4:hazard Hazard Function] 111 112 template <class RealType, class ``__Policy``> 113 RealType hazard(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist, const RealType& x); 114 115Returns the __hazard of /x/ and distribution /dist/. 116 117This function may return a __domain_error if the random variable is outside 118the defined range for the distribution. 119 120[equation hazard] 121 122[caution 123Some authors refer to this as the conditional failure 124density function rather than the hazard function.] 125 126[h4:chf Cumulative Hazard Function] 127 128 template <class RealType, class ``__Policy``> 129 RealType chf(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist, const RealType& x); 130 131Returns the __chf of /x/ and distribution /dist/. 132 133This function may return a __domain_error if the random variable is outside 134the defined range for the distribution. 135 136[equation chf] 137 138[caution 139Some authors refer to this as simply the "Hazard Function".] 140 141[h4:mean mean] 142 143 template<class RealType, class ``__Policy``> 144 RealType mean(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist); 145 146Returns the mean of the distribution /dist/. 147 148This function may return a __domain_error if the distribution does not have 149a defined mean (for example the Cauchy distribution). 150 151[h4:median median] 152 153 template<class RealType, class ``__Policy``> 154 RealType median(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist); 155 156Returns the median of the distribution /dist/. 157 158[h4:mode mode] 159 160 template<class RealType, ``__Policy``> 161 RealType mode(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist); 162 163Returns the mode of the distribution /dist/. 164 165This function may return a __domain_error if the distribution does not have 166a defined mode. 167 168[h4:pdf Probability Density Function] 169 170 template <class RealType, class ``__Policy``> 171 RealType pdf(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist, const RealType& x); 172 173For a continuous function, the probability density function (pdf) returns 174the probability that the variate has the value x. 175Since for continuous distributions the probability at a single point is actually zero, 176the probability is better expressed as the integral of the pdf between two points: 177see the __cdf. 178 179For a discrete distribution, the pdf is the probability that the 180variate takes the value x. 181 182This function may return a __domain_error if the random variable is outside 183the defined range for the distribution. 184 185For example, for a standard normal distribution the pdf looks like this: 186 187[$../graphs/pdf.png] 188 189[h4:range Range] 190 191 template<class RealType, class ``__Policy``> 192 std::pair<RealType, RealType> range(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist); 193 194Returns the valid range of the random variable over distribution /dist/. 195 196[h4:quantile Quantile] 197 198 template <class RealType, class ``__Policy``> 199 RealType quantile(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist, const RealType& p); 200 201The quantile is best viewed as the inverse of the __cdf, it returns 202a value /x/ such that `cdf(dist, x) == p`. 203 204This is also known as the /percent point function/, or /percentile/, or /fractile/, 205it is also the same as calculating the ['lower critical value] of a distribution. 206 207This function returns a __domain_error if the probability lies outside [0,1]. 208The function may return an __overflow_error if there is no finite value 209that has the specified probability. 210 211The following graph shows the quantile function for a standard normal 212distribution: 213 214[$../graphs/quantile.png] 215 216[h4:quantile_c Quantile from the complement of the probability.] 217See also [link math_toolkit.stat_tut.overview.complements complements]. 218 219 220 template <class Distribution, class RealType> 221 RealType quantile(const ``['Unspecified-Complement-Type]``<Distribution, RealType>& comp); 222 223This is the inverse of the __ccdf. It is calculated by wrapping 224the arguments in a call to the quantile function in a call to 225/complement/. For example: 226 227 // define a standard normal distribution: 228 boost::math::normal norm; 229 // print the value of x for which the complement 230 // of the probability is 0.05: 231 std::cout << quantile(complement(norm, 0.05)) << std::endl; 232 233The function computes a value /x/ such that 234`cdf(complement(dist, x)) == q` where /q/ is complement of the 235probability. 236 237[link why_complements Why complements?] 238 239This function is also called the inverse survival function, and is the 240same as calculating the ['upper critical value] of a distribution. 241 242This function returns a __domain_error if the probability lies outside [0,1]. 243The function may return an __overflow_error if there is no finite value 244that has the specified probability. 245 246The following graph show the inverse survival function for the normal 247distribution: 248 249[$../graphs/survival_inv.png] 250 251[h4:sd Standard Deviation] 252 253 template <class RealType, class ``__Policy``> 254 RealType standard_deviation(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist); 255 256Returns the standard deviation of distribution /dist/. 257 258This function may return a __domain_error if the distribution does not have 259a defined standard deviation. 260 261[h4:support support] 262 263 template<class RealType, class ``__Policy``> 264 std::pair<RealType, RealType> support(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist); 265 266Returns the supported range of random variable over the distribution /dist/. 267 268The distribution is said to be 'supported' over a range that is 269[@http://en.wikipedia.org/wiki/Probability_distribution 270 "the smallest closed set whose complement has probability zero"]. 271Non-mathematicians might say it means the 'interesting' smallest range 272of random variate x that has the cdf going from zero to unity. 273Outside are uninteresting zones where the pdf is zero, and the cdf zero or unity. 274 275[h4:variance Variance] 276 277 template <class RealType, class ``__Policy``> 278 RealType variance(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist); 279 280Returns the variance of the distribution /dist/. 281 282This function may return a __domain_error if the distribution does not have 283a defined variance. 284 285[h4:skewness Skewness] 286 287 template <class RealType, class ``__Policy``> 288 RealType skewness(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist); 289 290Returns the skewness of the distribution /dist/. 291 292This function may return a __domain_error if the distribution does not have 293a defined skewness. 294 295[h4:kurtosis Kurtosis] 296 297 template <class RealType, class ``__Policy``> 298 RealType kurtosis(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist); 299 300Returns the 'proper' kurtosis (normalized fourth moment) of the distribution /dist/. 301 302kurtosis = [beta][sub 2]= [mu][sub 4] / [mu][sub 2][super 2] 303 304Where [mu][sub i] is the i'th central moment of the distribution, and 305in particular [mu][sub 2] is the variance of the distribution. 306 307The kurtosis is a measure of the "peakedness" of a distribution. 308 309Note that the literature definition of kurtosis is confusing. 310The definition used here is that used by for example 311[@http://mathworld.wolfram.com/Kurtosis.html Wolfram MathWorld] 312(that includes a table of formulae for kurtosis excess for various distributions) 313but NOT the definition of 314[@http://en.wikipedia.org/wiki/Kurtosis kurtosis used by Wikipedia] 315which treats "kurtosis" and "kurtosis excess" as the same quantity. 316 317 kurtosis_excess = 'proper' kurtosis - 3 318 319This subtraction of 3 is convenient so that the ['kurtosis excess] 320of a normal distribution is zero. 321 322This function may return a __domain_error if the distribution does not have 323a defined kurtosis. 324 325'Proper' kurtosis can have a value from zero to + infinity. 326 327[h4:kurtosis_excess Kurtosis excess] 328 329 template <class RealType, ``__Policy``> 330 RealType kurtosis_excess(const ``['Distribution-Type]``<RealType, ``__Policy``>& dist); 331 332Returns the kurtosis excess of the distribution /dist/. 333 334kurtosis excess = [gamma][sub 2]= [mu][sub 4] / [mu][sub 2][super 2]- 3 = kurtosis - 3 335 336Where [mu][sub i] is the i'th central moment of the distribution, and 337in particular [mu][sub 2] is the variance of the distribution. 338 339The kurtosis excess is a measure of the "peakedness" of a distribution, and 340is more widely used than the "kurtosis proper". It is defined so that 341the kurtosis excess of a normal distribution is zero. 342 343This function may return a __domain_error if the distribution does not have 344a defined kurtosis excess. 345 346Kurtosis excess can have a value from -2 to + infinity. 347 348 kurtosis = kurtosis_excess +3; 349 350The kurtosis excess of a normal distribution is zero. 351 352[h4:cdfPQ P and Q] 353 354The terms P and Q are sometimes used to refer to the __cdf 355and its [link math_toolkit.dist_ref.nmp.ccdf complement] respectively. 356Lowercase p and q are sometimes used to refer to the values returned 357by these functions. 358 359[h4:percent Percent Point Function or Percentile] 360 361The percent point function, also known as the percentile, is the same as 362the __quantile. 363 364[h4:cdf_inv Inverse CDF Function.] 365 366The inverse of the cumulative distribution function, is the same as the 367__quantile. 368 369[h4:survival_inv Inverse Survival Function.] 370 371The inverse of the survival function, is the same as computing the 372[link math_toolkit.dist_ref.nmp.quantile_c quantile 373from the complement of the probability]. 374 375[h4:pmf Probability Mass Function] 376 377The Probability Mass Function is the same as the __pdf. 378 379The term Mass Function is usually applied to discrete distributions, 380while the term __pdf applies to continuous distributions. 381 382[h4:lower_critical Lower Critical Value.] 383 384The lower critical value calculates the value of the random variable 385given the area under the left tail of the distribution. 386It is equivalent to calculating the __quantile. 387 388[h4:upper_critical Upper Critical Value.] 389 390The upper critical value calculates the value of the random variable 391given the area under the right tail of the distribution. It is equivalent to 392calculating the [link math_toolkit.dist_ref.nmp.quantile_c quantile from the complement of the 393probability]. 394 395[h4:survival Survival Function] 396 397Refer to the __ccdf. 398 399[h4:entropy Entropy] 400 401The entropy (or differential entropy) of a continuous probability distribution /p/ is defined as 402 403[$../graphs/differential_entropy.svg] 404 405Note that the "natural" properties of the differential entropy do not uniquely specify a log base. 406In the Boost library, we /always/ use the natural logarithm to compute differential entropy. 407This choice of log base for entropy is sometimes referred to as "entropy measured in nats". 408See [@https://doi.org/10.1109/TIT.1978.1055832 On the entropy of continuous probability distributions] for more information. 409 410[endsect] [/section:nmp Non-Member Properties] 411 412[/ non_members.qbk 413 Copyright 2006 John Maddock and Paul A. Bristow. 414 Distributed under the Boost Software License, Version 1.0. 415 (See accompanying file LICENSE_1_0.txt or copy at 416 http://www.boost.org/LICENSE_1_0.txt). 417] 418 419
