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