| [section:beta_dist Beta Distribution] |
| |
| ``#include <boost/math/distributions/beta.hpp>`` |
| |
| namespace boost{ namespace math{ |
| |
| template <class RealType = double, |
| class ``__Policy`` = ``__policy_class`` > |
| class beta_distribution; |
| |
| // typedef beta_distribution<double> beta; |
| // Note that this is deliberately NOT provided, |
| // to avoid a clash with the function name beta. |
| |
| template <class RealType, class ``__Policy``> |
| class beta_distribution |
| { |
| public: |
| typedef RealType value_type; |
| typedef Policy policy_type; |
| // Constructor from two shape parameters, alpha & beta: |
| beta_distribution(RealType a, RealType b); |
| |
| // Parameter accessors: |
| RealType alpha() const; |
| RealType beta() const; |
| |
| // Parameter estimators of alpha or beta from mean and variance. |
| static RealType find_alpha( |
| RealType mean, // Expected value of mean. |
| RealType variance); // Expected value of variance. |
| |
| static RealType find_beta( |
| RealType mean, // Expected value of mean. |
| RealType variance); // Expected value of variance. |
| |
| // Parameter estimators from from |
| // either alpha or beta, and x and probability. |
| |
| static RealType find_alpha( |
| RealType beta, // from beta. |
| RealType x, // x. |
| RealType probability); // cdf |
| |
| static RealType find_beta( |
| RealType alpha, // alpha. |
| RealType x, // probability x. |
| RealType probability); // probability cdf. |
| }; |
| |
| }} // namespaces |
| |
| The class type `beta_distribution` represents a |
| [@http://en.wikipedia.org/wiki/Beta_distribution beta ] |
| [@http://en.wikipedia.org/wiki/Probability_distribution probability distribution function]. |
| |
| The [@http://mathworld.wolfram.com/BetaDistribution.htm beta distribution ] |
| is used as a [@http://en.wikipedia.org/wiki/Prior_distribution prior distribution] |
| for binomial proportions in |
| [@http://mathworld.wolfram.com/BayesianAnalysis.html Bayesian analysis]. |
| |
| See also: |
| [@http://documents.wolfram.com/calculationcenter/v2/Functions/ListsMatrices/Statistics/BetaDistribution.html beta distribution] |
| and [@http://en.wikipedia.org/wiki/Bayesian_statistics Bayesian statistics]. |
| |
| How the beta distribution is used for |
| [@http://home.uchicago.edu/~grynav/bayes/ABSLec5.ppt |
| Bayesian analysis of one parameter models] |
| is discussed by Jeff Grynaviski. |
| |
| The [@http://en.wikipedia.org/wiki/Probability_density_function probability density function PDF] |
| for the [@http://en.wikipedia.org/wiki/Beta_distribution beta distribution] |
| defined on the interval \[0,1\] is given by: |
| |
| f(x;[alpha],[beta]) = x[super[alpha] - 1] (1 - x)[super[beta] -1] / B([alpha], [beta]) |
| |
| where B([alpha], [beta]) is the |
| [@http://en.wikipedia.org/wiki/Beta_function beta function], |
| implemented in this library as __beta. Division by the beta function |
| ensures that the pdf is normalized to the range zero to unity. |
| |
| The following graph illustrates examples of the pdf for various values |
| of the shape parameters. Note the [alpha] = [beta] = 2 (blue line) |
| is dome-shaped, and might be approximated by a symmetrical triangular |
| distribution. |
| |
| [graph beta_pdf] |
| |
| If [alpha] = [beta] = 1, then it is a __space |
| [@http://en.wikipedia.org/wiki/Uniform_distribution_%28continuous%29 uniform distribution], |
| equal to unity in the entire interval x = 0 to 1. |
| If [alpha] __space and [beta] __space are < 1, then the pdf is U-shaped. |
| If [alpha] != [beta], then the shape is asymmetric |
| and could be approximated by a triangle |
| whose apex is away from the centre (where x = half). |
| |
| [h4 Member Functions] |
| |
| [h5 Constructor] |
| |
| beta_distribution(RealType alpha, RealType beta); |
| |
| Constructs a beta distribution with shape parameters /alpha/ and /beta/. |
| |
| Requires alpha,beta > 0,otherwise __domain_error is called. Note that |
| technically the beta distribution is defined for alpha,beta >= 0, but |
| it's not clear whether any program can actually make use of that latitude |
| or how many of the non-member functions can be usefully defined in that case. |
| Therefore for now, we regard it as an error if alpha or beta is zero. |
| |
| For example: |
| |
| beta_distribution<> mybeta(2, 5); |
| |
| Constructs a the beta distribution with alpha=2 and beta=5 (shown in yellow |
| in the graph above). |
| |
| [h5 Parameter Accessors] |
| |
| RealType alpha() const; |
| |
| Returns the parameter /alpha/ from which this distribution was constructed. |
| |
| RealType beta() const; |
| |
| Returns the parameter /beta/ from which this distribution was constructed. |
| |
| So for example: |
| |
| beta_distribution<> mybeta(2, 5); |
| assert(mybeta.alpha() == 2.); // mybeta.alpha() returns 2 |
| assert(mybeta.beta() == 5.); // mybeta.beta() returns 5 |
| |
| [h4 Parameter Estimators] |
| |
| Two pairs of parameter estimators are provided. |
| |
| One estimates either [alpha] __space or [beta] __space |
| from presumed-known mean and variance. |
| |
| The other pair estimates either [alpha] __space or [beta] __space from |
| the cdf and x. |
| |
| It is also possible to estimate [alpha] __space and [beta] __space from |
| 'known' mode & quantile. For example, calculators are provided by the |
| [@http://www.ausvet.com.au/pprev/content.php?page=PPscript |
| Pooled Prevalence Calculator] and |
| [@http://www.epi.ucdavis.edu/diagnostictests/betabuster.html Beta Buster] |
| but this is not yet implemented here. |
| |
| static RealType find_alpha( |
| RealType mean, // Expected value of mean. |
| RealType variance); // Expected value of variance. |
| |
| Returns the unique value of [alpha][space] that corresponds to a |
| beta distribution with mean /mean/ and variance /variance/. |
| |
| static RealType find_beta( |
| RealType mean, // Expected value of mean. |
| RealType variance); // Expected value of variance. |
| |
| Returns the unique value of [beta][space] that corresponds to a |
| beta distribution with mean /mean/ and variance /variance/. |
| |
| static RealType find_alpha( |
| RealType beta, // from beta. |
| RealType x, // x. |
| RealType probability); // probability cdf |
| |
| Returns the value of [alpha][space] that gives: |
| `cdf(beta_distribution<RealType>(alpha, beta), x) == probability`. |
| |
| static RealType find_beta( |
| RealType alpha, // alpha. |
| RealType x, // probability x. |
| RealType probability); // probability cdf. |
| |
| Returns the value of [beta][space] that gives: |
| `cdf(beta_distribution<RealType>(alpha, beta), x) == probability`. |
| |
| [h4 Non-member Accessor Functions] |
| |
| All the [link math_toolkit.dist.dist_ref.nmp usual non-member accessor functions] |
| that are generic to all distributions are supported: __usual_accessors. |
| |
| The formulae for calculating these are shown in the table below, and at |
| [@http://mathworld.wolfram.com/BetaDistribution.html Wolfram Mathworld]. |
| |
| [h4 Applications] |
| |
| The beta distribution can be used to model events constrained |
| to take place within an interval defined by a minimum and maximum value: |
| so it is used in project management systems. |
| |
| It is also widely used in [@http://en.wikipedia.org/wiki/Bayesian_inference Bayesian statistical inference]. |
| |
| [h4 Related distributions] |
| |
| The beta distribution with both [alpha] __space and [beta] = 1 follows a |
| [@http://en.wikipedia.org/wiki/Uniform_distribution_%28continuous%29 uniform distribution]. |
| |
| The [@http://en.wikipedia.org/wiki/Triangular_distribution triangular] |
| is used when less precise information is available. |
| |
| The [@http://en.wikipedia.org/wiki/Binomial_distribution binomial distribution] |
| is closely related when [alpha] __space and [beta] __space are integers. |
| |
| With integer values of [alpha] __space and [beta] __space the distribution B(i, j) is |
| that of the j-th highest of a sample of i + j + 1 independent random variables |
| uniformly distributed between 0 and 1. |
| The cumulative probability from 0 to x is thus |
| the probability that the j-th highest value is less than x. |
| Or it is the probability that that at least i of the random variables are less than x, |
| a probability given by summing over the __binomial_distrib |
| with its p parameter set to x. |
| |
| [h4 Accuracy] |
| |
| This distribution is implemented using the |
| [link math_toolkit.special.sf_beta.beta_function beta functions] __beta and |
| [link math_toolkit.special.sf_beta.ibeta_function incomplete beta functions] __ibeta and __ibetac; |
| please refer to these functions for information on accuracy. |
| |
| [h4 Implementation] |
| |
| In the following table /a/ and /b/ are the parameters [alpha][space] and [beta], |
| /x/ is the random variable, /p/ is the probability and /q = 1-p/. |
| |
| [table |
| [[Function][Implementation Notes]] |
| [[pdf] |
| [f(x;[alpha],[beta]) = x[super[alpha] - 1] (1 - x)[super[beta] -1] / B([alpha], [beta]) |
| |
| Implemented using __ibeta_derivative(a, b, x).]] |
| |
| [[cdf][Using the incomplete beta function __ibeta(a, b, x)]] |
| [[cdf complement][__ibetac(a, b, x)]] |
| [[quantile][Using the inverse incomplete beta function __ibeta_inv(a, b, p)]] |
| [[quantile from the complement][__ibetac_inv(a, b, q)]] |
| [[mean][`a/(a+b)`]] |
| [[variance][`a * b / (a+b)^2 * (a + b + 1)`]] |
| [[mode][`(a-1) / (a + b - 2)`]] |
| [[skewness][`2 (b-a) sqrt(a+b+1)/(a+b+2) * sqrt(a * b)`]] |
| [[kurtosis excess][ [equation beta_dist_kurtosis] ]] |
| [[kurtosis][`kurtosis + 3`]] |
| [[parameter estimation][ ]] |
| [[alpha |
| |
| from mean and variance][`mean * (( (mean * (1 - mean)) / variance)- 1)`]] |
| [[beta |
| |
| from mean and variance][`(1 - mean) * (((mean * (1 - mean)) /variance)-1)`]] |
| [[The member functions `find_alpha` and `find_beta` |
| |
| from cdf and probability x |
| |
| and *either* `alpha` or `beta`] |
| [Implemented in terms of the inverse incomplete beta functions |
| |
| __ibeta_inva, and __ibeta_invb respectively.]] |
| [[`find_alpha`][`ibeta_inva(beta, x, probability)`]] |
| [[`find_beta`][`ibeta_invb(alpha, x, probability)`]] |
| ] |
| |
| [h4 References] |
| |
| [@http://en.wikipedia.org/wiki/Beta_distribution Wikipedia Beta distribution] |
| |
| [@http://www.itl.nist.gov/div898/handbook/eda/section3/eda366h.htm NIST Exploratory Data Analysis] |
| |
| [@http://mathworld.wolfram.com/BetaDistribution.html Wolfram MathWorld] |
| |
| [endsect][/section:beta_dist beta] |
| |
| [/ beta.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). |
| ] |