]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [section:students_t_dist Students t Distribution] |
2 | ||
3 | ``#include <boost/math/distributions/students_t.hpp>`` | |
4 | ||
5 | namespace boost{ namespace math{ | |
6 | ||
7 | template <class RealType = double, | |
8 | class ``__Policy`` = ``__policy_class`` > | |
9 | class students_t_distribution; | |
10 | ||
11 | typedef students_t_distribution<> students_t; | |
12 | ||
13 | template <class RealType, class ``__Policy``> | |
14 | class students_t_distribution | |
15 | { | |
16 | typedef RealType value_type; | |
17 | typedef Policy policy_type; | |
18 | ||
19 | // Construct: | |
20 | students_t_distribution(const RealType& v); | |
21 | ||
22 | // Accessor: | |
23 | RealType degrees_of_freedom()const; | |
24 | ||
25 | // degrees of freedom estimation: | |
26 | static RealType find_degrees_of_freedom( | |
27 | RealType difference_from_mean, | |
28 | RealType alpha, | |
29 | RealType beta, | |
30 | RealType sd, | |
31 | RealType hint = 100); | |
32 | }; | |
33 | ||
34 | }} // namespaces | |
35 | ||
36 | A statistical distribution published by William Gosset in 1908. | |
37 | His employer, Guinness Breweries, required him to publish under a | |
38 | pseudonym (possibly to hide that they were using statistics), | |
39 | so he chose "Student". Given N independent measurements, let | |
40 | ||
41 | [equation students_t_dist] | |
42 | ||
43 | where /M/ is the population mean,[' ''' μ '''] is the sample mean, and /s/ is the | |
44 | sample variance. | |
45 | ||
46 | Student's t-distribution is defined as the distribution of the random | |
47 | variable t which is - very loosely - the "best" that we can do not | |
48 | knowing the true standard deviation of the sample. It has the PDF: | |
49 | ||
50 | [equation students_t_ref1] | |
51 | ||
52 | The Student's t-distribution takes a single parameter: the number of | |
53 | degrees of freedom of the sample. When the degrees of freedom is | |
54 | /one/ then this distribution is the same as the Cauchy-distribution. | |
55 | As the number of degrees of freedom tends towards infinity, then this | |
56 | distribution approaches the normal-distribution. The following graph | |
57 | illustrates how the PDF varies with the degrees of freedom [nu]: | |
58 | ||
59 | [graph students_t_pdf] | |
60 | ||
61 | [h4 Member Functions] | |
62 | ||
63 | students_t_distribution(const RealType& v); | |
64 | ||
65 | Constructs a Student's t-distribution with /v/ degrees of freedom. | |
66 | ||
67 | Requires /v/ > 0, otherwise calls __domain_error. Note that | |
68 | non-integral degrees of freedom are supported, | |
69 | and are meaningful under certain circumstances. | |
70 | ||
71 | RealType degrees_of_freedom()const; | |
72 | ||
73 | Returns the number of degrees of freedom of this distribution. | |
74 | ||
75 | static RealType find_degrees_of_freedom( | |
76 | RealType difference_from_mean, | |
77 | RealType alpha, | |
78 | RealType beta, | |
79 | RealType sd, | |
80 | RealType hint = 100); | |
81 | ||
82 | Returns the number of degrees of freedom required to observe a significant | |
83 | result in the Student's t test when the mean differs from the "true" | |
84 | mean by /difference_from_mean/. | |
85 | ||
86 | [variablelist | |
87 | [[difference_from_mean][The difference between the true mean and the sample mean | |
88 | that we wish to show is significant.]] | |
89 | [[alpha][The maximum acceptable probability of rejecting the null hypothesis | |
90 | when it is in fact true.]] | |
91 | [[beta][The maximum acceptable probability of failing to reject the null hypothesis | |
92 | when it is in fact false.]] | |
93 | [[sd][The sample standard deviation.]] | |
94 | [[hint][A hint for the location to start looking for the result, a good choice for this | |
95 | would be the sample size of a previous borderline Student's t test.]] | |
96 | ] | |
97 | ||
98 | [note | |
99 | Remember that for a two-sided test, you must divide alpha by two | |
100 | before calling this function.] | |
101 | ||
102 | For more information on this function see the | |
103 | [@http://www.itl.nist.gov/div898/handbook/prc/section2/prc222.htm | |
104 | NIST Engineering Statistics Handbook]. | |
105 | ||
106 | [h4 Non-member Accessors] | |
107 | ||
108 | All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] that are generic to all | |
109 | distributions are supported: __usual_accessors. | |
110 | ||
111 | The domain of the random variable is \[-[infin], +[infin]\]. | |
112 | ||
113 | [h4 Examples] | |
114 | ||
115 | Various [link math_toolkit.stat_tut.weg.st_eg worked examples] are available illustrating the use of the Student's t | |
116 | distribution. | |
117 | ||
118 | [h4 Accuracy] | |
119 | ||
120 | The normal distribution is implemented in terms of the | |
121 | [link math_toolkit.sf_beta.ibeta_function incomplete beta function] | |
122 | and [link math_toolkit.sf_beta.ibeta_inv_function its inverses], | |
123 | refer to accuracy data on those functions for more information. | |
124 | ||
125 | [h4 Implementation] | |
126 | ||
127 | In the following table /v/ is the degrees of freedom of the distribution, | |
128 | /t/ is the random variate, /p/ is the probability and /q = 1-p/. | |
129 | ||
130 | [table | |
131 | [[Function][Implementation Notes]] | |
132 | [[pdf][Using the relation: pdf = (v \/ (v + t[super 2]))[super (1+v)\/2 ] / (sqrt(v) * __beta(v\/2, 0.5)) ]] | |
133 | [[cdf][Using the relations: | |
134 | ||
135 | p = 1 - z /iff t > 0/ | |
136 | ||
137 | p = z /otherwise/ | |
138 | ||
139 | where z is given by: | |
140 | ||
141 | __ibeta(v \/ 2, 0.5, v \/ (v + t[super 2])) \/ 2 ['iff v < 2t[super 2]] | |
142 | ||
143 | __ibetac(0.5, v \/ 2, t[super 2 ] / (v + t[super 2]) \/ 2 /otherwise/]] | |
144 | [[cdf complement][Using the relation: q = cdf(-t) ]] | |
145 | [[quantile][Using the relation: t = sign(p - 0.5) * sqrt(v * y \/ x) | |
146 | ||
147 | where: | |
148 | ||
149 | x = __ibeta_inv(v \/ 2, 0.5, 2 * min(p, q)) | |
150 | ||
151 | y = 1 - x | |
152 | ||
153 | The quantities /x/ and /y/ are both returned by __ibeta_inv | |
154 | without the subtraction implied above.]] | |
155 | [[quantile from the complement][Using the relation: t = -quantile(q)]] | |
156 | [[mode][0]] | |
157 | [[mean][0]] | |
158 | [[variance][if (v > 2) v \/ (v - 2) else NaN]] | |
159 | [[skewness][if (v > 3) 0 else NaN ]] | |
160 | [[kurtosis][if (v > 4) 3 * (v - 2) \/ (v - 4) else NaN]] | |
161 | [[kurtosis excess][if (v > 4) 6 \/ (df - 4) else NaN]] | |
162 | ] | |
163 | ||
164 | If the moment index /k/ is less than /v/, then the moment is undefined. | |
165 | Evaluating the moment will throw a __domain_error unless ignored by a policy, | |
166 | when it will return `std::numeric_limits<>::quiet_NaN();` | |
167 | ||
168 | (For simplicity, we have not implemented the return of infinity in some cases | |
169 | as suggested by [@http://en.wikipedia.org/wiki/Student%27s_t-distribution Wikipedia Student's t]. | |
170 | See also [@https://svn.boost.org/trac/boost/ticket/7177].) | |
171 | ||
172 | [endsect] [/section:students_t_dist Students t] | |
173 | ||
174 | [/ students_t.qbk | |
175 | Copyright 2006, 2012 John Maddock and Paul A. Bristow. | |
176 | Distributed under the Boost Software License, Version 1.0. | |
177 | (See accompanying file LICENSE_1_0.txt or copy at | |
178 | http://www.boost.org/LICENSE_1_0.txt). | |
179 | ] | |
180 |