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

   1 [section:beta_dist Beta Distribution]
   2
   3 ``#include <boost/math/distributions/beta.hpp>``
   4
   5    namespace boost{ namespace math{
   6
   7     template <class RealType = double,
   8               class ``__Policy``   = ``__policy_class`` >
   9    class beta_distribution;
  10
  11    // typedef beta_distribution<double> beta;
  12    // Note that this is deliberately NOT provided,
  13    // to avoid a clash with the function name beta.
  14
  15    template <class RealType, class ``__Policy``>
  16    class beta_distribution
  17    {
  18    public:
  19       typedef RealType  value_type;
  20       typedef Policy    policy_type;
  21       // Constructor from two shape parameters, alpha & beta:
  22       beta_distribution(RealType a, RealType b);
  23
  24       // Parameter accessors:
  25       RealType alpha() const;
  26       RealType beta() const;
  27
  28       // Parameter estimators of alpha or beta from mean and variance.
  29       static RealType find_alpha(
  30         RealType mean, // Expected value of mean.
  31         RealType variance); // Expected value of variance.
  32
  33       static RealType find_beta(
  34         RealType mean, // Expected value of mean.
  35         RealType variance); // Expected value of variance.
  36
  37       // Parameter estimators from
  38       // either alpha or beta, and x and probability.
  39
  40       static RealType find_alpha(
  41         RealType beta, // from beta.
  42         RealType x, //  x.
  43         RealType probability); // cdf
  44
  45       static RealType find_beta(
  46         RealType alpha, // alpha.
  47         RealType x, // probability x.
  48         RealType probability); // probability cdf.
  49    };
  50
  51    }} // namespaces
  52
  53 The class type `beta_distribution` represents a
  54 [@http://en.wikipedia.org/wiki/Beta_distribution beta ]
  55 [@http://en.wikipedia.org/wiki/Probability_distribution probability distribution function].
  56
  57 The [@http://mathworld.wolfram.com/BetaDistribution.htm beta distribution ]
  58 is used as a [@http://en.wikipedia.org/wiki/Prior_distribution prior distribution]
  59 for binomial proportions in
  60 [@http://mathworld.wolfram.com/BayesianAnalysis.html Bayesian analysis].
  61
  62 See also:
  63 [@http://documents.wolfram.com/calculationcenter/v2/Functions/ListsMatrices/Statistics/BetaDistribution.html beta distribution]
  64 and [@http://en.wikipedia.org/wiki/Bayesian_statistics Bayesian statistics].
  65
  66 How the beta distribution is used for
  67 [@http://home.uchicago.edu/~grynav/bayes/ABSLec5.ppt
  68 Bayesian analysis of one parameter models]
  69 is discussed by Jeff Grynaviski.
  70
  71 The [@http://en.wikipedia.org/wiki/Probability_density_function probability density function PDF]
  72 for the [@http://en.wikipedia.org/wiki/Beta_distribution beta distribution]
  73 defined on the interval \[0,1\] is given by:
  74
  75 f(x;[alpha],[beta]) = x[super[alpha] - 1] (1 - x)[super[beta] -1] / B([alpha], [beta])
  76
  77 where B([alpha], [beta]) is the
  78 [@http://en.wikipedia.org/wiki/Beta_function beta function],
  79 implemented in this library as __beta.  Division by the beta function
  80 ensures that the pdf is normalized to the range zero to unity.
  81
  82 The following graph illustrates examples of the pdf for various values
  83 of the shape parameters.  Note the [alpha] = [beta] = 2 (blue line)
  84 is dome-shaped, and might be approximated by a symmetrical triangular
  85 distribution.
  86
  87 [graph beta_pdf]
  88
  89 If [alpha] = [beta] = 1, then it is a __space
  90 [@http://en.wikipedia.org/wiki/Uniform_distribution_%28continuous%29 uniform distribution],
  91 equal to unity in the entire interval x = 0 to 1.
  92 If [alpha] __space and [beta] __space are < 1, then the pdf is U-shaped.
  93 If [alpha] != [beta], then the shape is asymmetric
  94 and could be approximated by a triangle
  95 whose apex is away from the centre (where x = half).
  96
  97 [h4 Member Functions]
  98
  99 [h5 Constructor]
 100
 101    beta_distribution(RealType alpha, RealType beta);
 102
 103 Constructs a beta distribution with shape parameters /alpha/ and /beta/.
 104
 105 Requires alpha,beta > 0,otherwise __domain_error is called.  Note that
 106 technically the beta distribution is defined for alpha,beta >= 0, but
 107 it's not clear whether any program can actually make use of that latitude
 108 or how many of the non-member functions can be usefully defined in that case.
 109 Therefore for now, we regard it as an error if alpha or beta is zero.
 110
 111 For example:
 112
 113    beta_distribution<> mybeta(2, 5);
 114
 115 Constructs a the beta distribution with alpha=2 and beta=5 (shown in yellow
 116 in the graph above).
 117
 118 [h5 Parameter Accessors]
 119
 120    RealType alpha() const;
 121
 122 Returns the parameter /alpha/ from which this distribution was constructed.
 123
 124    RealType beta() const;
 125
 126 Returns the parameter /beta/ from which this distribution was constructed.
 127
 128 So for example:
 129
 130    beta_distribution<> mybeta(2, 5);
 131    assert(mybeta.alpha() == 2.);  // mybeta.alpha() returns 2
 132    assert(mybeta.beta() == 5.);   // mybeta.beta()  returns 5
 133
 134 [h4 Parameter Estimators]
 135
 136 Two pairs of parameter estimators are provided.
 137
 138 One estimates either [alpha] __space or [beta] __space
 139 from presumed-known mean and variance.
 140
 141 The other pair estimates either [alpha] __space or [beta] __space from
 142 the cdf and x.
 143
 144 It is also possible to estimate [alpha] __space and  [beta] __space from
 145 'known' mode & quantile.  For example, calculators are provided by the
 146 [@http://www.ausvet.com.au/pprev/content.php?page=PPscript
 147 Pooled Prevalence Calculator] and
 148 [@http://www.epi.ucdavis.edu/diagnostictests/betabuster.html Beta Buster]
 149 but this is not yet implemented here.
 150
 151       static RealType find_alpha(
 152         RealType mean, // Expected value of mean.
 153         RealType variance); // Expected value of variance.
 154
 155 Returns the unique value of [alpha][space] that corresponds to a
 156 beta distribution with mean /mean/ and variance /variance/.
 157
 158       static RealType find_beta(
 159         RealType mean, // Expected value of mean.
 160         RealType variance); // Expected value of variance.
 161
 162 Returns the unique value of [beta][space] that corresponds to a
 163 beta distribution with mean /mean/ and variance /variance/.
 164
 165       static RealType find_alpha(
 166         RealType beta, // from beta.
 167         RealType x, //  x.
 168         RealType probability); // probability cdf
 169
 170 Returns the value of [alpha][space] that gives:
 171 `cdf(beta_distribution<RealType>(alpha, beta), x) == probability`.
 172
 173       static RealType find_beta(
 174         RealType alpha, // alpha.
 175         RealType x, // probability x.
 176         RealType probability); // probability cdf.
 177
 178 Returns the value of [beta][space] that gives:
 179 `cdf(beta_distribution<RealType>(alpha, beta), x) == probability`.
 180
 181 [h4 Non-member Accessor Functions]
 182
 183 All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
 184 that are generic to all distributions are supported: __usual_accessors.
 185
 186 The formulae for calculating these are shown in the table below, and at
 187 [@http://mathworld.wolfram.com/BetaDistribution.html Wolfram Mathworld].
 188
 189 [h4 Applications]
 190
 191 The beta distribution can be used to model events constrained
 192 to take place within an interval defined by a minimum and maximum value:
 193 so it is used in project management systems.
 194
 195 It is also widely used in [@http://en.wikipedia.org/wiki/Bayesian_inference Bayesian statistical inference].
 196
 197 [h4 Related distributions]
 198
 199 The beta distribution with both [alpha]  __space and [beta] = 1 follows a
 200 [@http://en.wikipedia.org/wiki/Uniform_distribution_%28continuous%29 uniform distribution].
 201
 202 The [@http://en.wikipedia.org/wiki/Triangular_distribution triangular]
 203 is used when less precise information is available.
 204
 205 The [@http://en.wikipedia.org/wiki/Binomial_distribution binomial distribution]
 206 is closely related when [alpha]  __space and [beta]  __space are integers.
 207
 208 With integer values of [alpha]  __space and [beta]  __space the distribution B(i, j) is
 209 that of the j-th highest of a sample of i + j + 1 independent random variables
 210 uniformly distributed between 0 and 1.
 211 The cumulative probability from 0 to x is thus
 212 the probability that the j-th highest value is less than x.
 213 Or it is the probability that at least i of the random variables are less than x,
 214 a probability given by summing over the __binomial_distrib
 215 with its p parameter set to x.
 216
 217 [h4 Accuracy]
 218
 219 This distribution is implemented using the
 220 [link math_toolkit.sf_beta.beta_function beta functions] __beta and
 221 [link math_toolkit.sf_beta.ibeta_function incomplete beta functions] __ibeta and __ibetac;
 222 please refer to these functions for information on accuracy.
 223
 224 [h4 Implementation]
 225
 226 In the following table /a/ and /b/ are the parameters [alpha][space] and [beta],
 227 /x/ is the random variable, /p/ is the probability and /q = 1-p/.
 228
 229 [table
 230 [[Function][Implementation Notes]]
 231 [[pdf]
 232    [f(x;[alpha],[beta]) = x[super[alpha] - 1] (1 - x)[super[beta] -1] / B([alpha], [beta])
 233
 234     Implemented using __ibeta_derivative(a, b, x).]]
 235
 236 [[cdf][Using the incomplete beta function __ibeta(a, b, x)]]
 237 [[cdf complement][__ibetac(a, b, x)]]
 238 [[quantile][Using the inverse incomplete beta function __ibeta_inv(a, b, p)]]
 239 [[quantile from the complement][__ibetac_inv(a, b, q)]]
 240 [[mean][`a/(a+b)`]]
 241 [[variance][`a * b / (a+b)^2 * (a + b + 1)`]]
 242 [[mode][`(a-1) / (a + b - 2)`]]
 243 [[skewness][`2 (b-a) sqrt(a+b+1)/(a+b+2) * sqrt(a * b)`]]
 244 [[kurtosis excess][ [equation beta_dist_kurtosis]  ]]
 245 [[kurtosis][`kurtosis + 3`]]
 246 [[parameter estimation][ ]]
 247 [[alpha
 248
 249    from mean and variance][`mean * (( (mean * (1 - mean)) / variance)- 1)`]]
 250 [[beta
 251
 252   from mean and variance][`(1 - mean) * (((mean * (1 - mean)) /variance)-1)`]]
 253 [[The member functions `find_alpha` and `find_beta`
 254
 255   from cdf and probability x
 256
 257   and *either* `alpha` or `beta`]
 258       [Implemented in terms of the inverse incomplete beta functions
 259
 260 __ibeta_inva, and __ibeta_invb respectively.]]
 261 [[`find_alpha`][`ibeta_inva(beta, x, probability)`]]
 262 [[`find_beta`][`ibeta_invb(alpha, x, probability)`]]
 263 ]
 264
 265 [h4 References]
 266
 267 [@http://en.wikipedia.org/wiki/Beta_distribution Wikipedia Beta distribution]
 268
 269 [@http://www.itl.nist.gov/div898/handbook/eda/section3/eda366h.htm NIST Exploratory Data Analysis]
 270
 271 [@http://mathworld.wolfram.com/BetaDistribution.html Wolfram MathWorld]
 272
 273 [endsect][/section:beta_dist beta]
 274
 275 [/ beta.qbk
 276   Copyright 2006 John Maddock and Paul A. Bristow.
 277   Distributed under the Boost Software License, Version 1.0.
 278   (See accompanying file LICENSE_1_0.txt or copy at
 279   http://www.boost.org/LICENSE_1_0.txt).
 280 ]