libs/math/doc/distributions/students_t.qbk

   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
  36 Student's t-distribution is 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 to improve beer quality),
  39 so he chose "Student".
  40
  41 Given N independent measurements, let
  42
  43 [equation students_t_dist]
  44
  45 where /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]
  48 is defined as the distribution of the random
  49 variable t which is  - very loosely - the "best" that we can do while not
  50 knowing the true standard deviation of the sample.  It has the PDF:
  51
  52 [equation students_t_ref1]
  53
  54 The Student's t-distribution takes a single parameter: the number of
  55 degrees of freedom of the sample. When the degrees of freedom is
  56 /one/ then this distribution is the same as the Cauchy-distribution.
  57 As the number of degrees of freedom tends towards infinity, then this
  58 distribution approaches the normal-distribution.  The following graph
  59 illustrates 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
  67 Constructs a Student's t-distribution with /v/ degrees of freedom.
  68
  69 Requires /v/ > 0, including infinity (if RealType permits),
  70 otherwise calls __domain_error.  Note that
  71 non-integral degrees of freedom are supported,
  72 and are meaningful under certain circumstances.
  73
  74    RealType degrees_of_freedom()const;
  75
  76 returns 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
  85 returns the number of degrees of freedom required to observe a significant
  86 result in the Student's t test when the mean differs from the "true"
  87 mean 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
 102 Remember that for a two-sided test, you must divide alpha by two
 103 before calling this function.]
 104
 105 For more information on this function see the
 106 [@http://www.itl.nist.gov/div898/handbook/prc/section2/prc222.htm
 107 NIST Engineering Statistics Handbook].
 108
 109 [h4 Non-member Accessors]
 110
 111 All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] that are generic to all
 112 distributions are supported: __usual_accessors.
 113
 114 The domain of the random variable is \[-[infin], +[infin]\].
 115
 116 [h4 Examples]
 117
 118 Various [link math_toolkit.stat_tut.weg.st_eg worked examples] are available illustrating the use of the Student's t
 119 distribution.
 120
 121 [h4 Accuracy]
 122
 123 The normal distribution is implemented in terms of the
 124 [link math_toolkit.sf_beta.ibeta_function incomplete beta function]
 125 and [link math_toolkit.sf_beta.ibeta_inv_function its inverses],
 126 refer to accuracy data on those functions for more information.
 127
 128 [h4 Implementation]
 129
 130 In 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
 142 where 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
 150 where:
 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
 156 The quantities /x/ and /y/ are both returned by __ibeta_inv
 157 without 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
 167 If the moment index /k/ is less than /v/, then the moment is undefined.
 168 Evaluating the moment will throw a __domain_error unless ignored by a policy,
 169 when 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.
 174 But we have not implemented the return of infinity
 175 as suggested by [@http://en.wikipedia.org/wiki/Student%27s_t-distribution Wikipedia Student's t],
 176 instead throwing a domain error or return NaN.
 177 See 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