]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | ] |