ceph/src/boost/libs/math/doc/distributions/nc_t.qbk

   1 [section:nc_t_dist Noncentral T Distribution]
   2
   3 ``#include <boost/math/distributions/non_central_t.hpp>``
   4
   5    namespace boost{ namespace math{
   6
   7    template <class RealType = double,
   8              class ``__Policy``   = ``__policy_class`` >
   9    class non_central_t_distribution;
  10
  11    typedef non_central_t_distribution<> non_central_t;
  12
  13    template <class RealType, class ``__Policy``>
  14    class non_central_t_distribution
  15    {
  16    public:
  17       typedef RealType  value_type;
  18       typedef Policy    policy_type;
  19
  20       // Constructor:
  21       non_central_t_distribution(RealType v, RealType delta);
  22
  23       // Accessor to degrees_of_freedom parameter v:
  24       RealType degrees_of_freedom()const;
  25
  26       // Accessor to non-centrality parameter delta:
  27       RealType non_centrality()const;
  28    };
  29
  30    }} // namespaces
  31
  32 The noncentral T distribution is a generalization of the __students_t_distrib.
  33 Let X have a normal distribution with mean [delta] and variance 1, and let
  34 [nu] S[super 2] have
  35 a chi-squared distribution with degrees of freedom [nu]. Assume that
  36 X and S[super 2] are independent. The
  37 distribution of t[sub [nu]]([delta])=X/S is called a
  38 noncentral t distribution with degrees of freedom [nu] and noncentrality
  39 parameter [delta].
  40
  41 This gives the following PDF:
  42
  43 [equation nc_t_ref1]
  44
  45 where [sub 1]F[sub 1](a;b;x) is a confluent hypergeometric function.
  46
  47 The following graph illustrates how the distribution changes
  48 for different values of [nu] and [delta]:
  49
  50 [graph nc_t_pdf]
  51 [graph nc_t_cdf]
  52
  53 [h4 Member Functions]
  54
  55       non_central_t_distribution(RealType v, RealType delta);
  56
  57 Constructs a non-central t distribution with degrees of freedom
  58 parameter /v/ and non-centrality parameter /delta/.
  59
  60 Requires /v/ > 0 (including positive infinity) and finite /delta/, otherwise calls __domain_error.
  61
  62       RealType degrees_of_freedom()const;
  63
  64 Returns the parameter /v/ from which this object was constructed.
  65
  66       RealType non_centrality()const;
  67
  68 Returns the non-centrality parameter /delta/ from which this object was constructed.
  69
  70 [h4 Non-member Accessors]
  71
  72 All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
  73 that are generic to all distributions are supported: __usual_accessors.
  74
  75 The domain of the random variable is \[-[infin], +[infin]\].
  76
  77 [h4 Accuracy]
  78
  79 The following table shows the peak errors
  80 (in units of [@http://en.wikipedia.org/wiki/Machine_epsilon epsilon])
  81 found on various platforms with various floating-point types.
  82 Unless otherwise specified, any floating-point type that is narrower
  83 than the one shown will have __zero_error.
  84
  85 [table_non_central_t_CDF]
  86
  87 [table_non_central_t_CDF_complement]
  88
  89 [caution The complexity of the current algorithm is dependent upon
  90 [delta][super 2]: consequently the time taken to evaluate the CDF
  91 increases rapidly for [delta] > 500, likewise the accuracy decreases
  92 rapidly for very large [delta].]
  93
  94 Accuracy for the quantile and PDF functions should be broadly similar.
  95 The /mode/ is determined numerically and cannot
  96 in principal be more accurate than the square root of
  97 floating-point type FPT epsilon, accessed using `boost::math::tools::epsilon<FPT>()`.
  98 For 64-bit `double`, epsilon is about 1e-16, so the fractional accuracy is limited to 1e-8.
  99
 100 [h4 Tests]
 101
 102 There are two sets of tests of this distribution:
 103
 104 Basic sanity checks compare this implementation to the test values given in
 105 "Computing discrete mixtures of continuous
 106 distributions: noncentral chisquare, noncentral t
 107 and the distribution of the square of the sample
 108 multiple correlation coefficient."
 109 Denise Benton, K. Krishnamoorthy,
 110 Computational Statistics & Data Analysis 43 (2003) 249-267.
 111
 112 Accuracy checks use test data computed with this
 113 implementation and arbitary precision interval arithmetic:
 114 this test data is believed to be accurate to at least 50
 115 decimal places.
 116
 117 The cases of large (or infinite) [nu] and/or large [delta] has received special
 118 treatment to avoid catastrophic loss of accuracy.
 119 New tests have been added to confirm the improvement achieved.
 120
 121 From Boost 1.52, degrees of freedom [nu] can be +[infin]
 122 when the normal distribution located at [delta]
 123 (equivalent to the central Student's t distribution)
 124 is used in place for accuracy and speed.
 125
 126 [h4 Implementation]
 127
 128 The CDF is computed using a modification of the method
 129 described in
 130 "Computing discrete mixtures of continuous
 131 distributions: noncentral chisquare, noncentral t
 132 and the distribution of the square of the sample
 133 multiple correlation coefficient."
 134 Denise Benton, K. Krishnamoorthy,
 135 Computational Statistics & Data Analysis 43 (2003) 249-267.
 136
 137 This uses the following formula for the CDF:
 138
 139 [equation nc_t_ref2]
 140
 141 Where I[sub x](a,b) is the incomplete beta function, and
 142 [Phi](x) is the normal CDF at x.
 143
 144 Iteration starts at the largest of the Poisson weighting terms
 145 (at i = [delta][super 2] / 2) and then proceeds in both directions
 146 as per Benton and Krishnamoorthy's paper.
 147
 148 Alternatively, by considering what happens when t = [infin], we have
 149 x = 1, and therefore I[sub x](a,b) = 1 and:
 150
 151 [equation nc_t_ref3]
 152
 153 From this we can easily show that:
 154
 155 [equation nc_t_ref4]
 156
 157 and therefore we have a means to compute either the probability or its
 158 complement directly without the risk of cancellation error.  The
 159 crossover criterion for choosing whether to calculate the CDF or
 160 its complement is the same as for the
 161 __non_central_beta_distrib.
 162
 163 The PDF can be computed by a very similar method using:
 164
 165 [equation nc_t_ref5]
 166
 167 Where I[sub x][super '](a,b) is the derivative of the incomplete beta function.
 168
 169 For both the PDF and CDF we switch to approximating the distribution by a
 170 Student's t distribution centred on [delta] when [nu] is very large.
 171 The crossover location appears to be when [delta]/(4[nu]) < [epsilon],
 172 this location was estimated by inspection of equation 2.6 in
 173 "A Comparison of Approximations To Percentiles of the
 174 Noncentral t-Distribution".  H. Sahai and M. M. Ojeda,
 175 Revista Investigacion Operacional Vol 21, No 2, 2000, page 123.
 176
 177 Equation 2.6 is a Fisher-Cornish expansion by Eeden and Johnson.
 178 The second term includes the ratio [delta]/(4[nu]),
 179 so when this term become negligible, this and following terms can be ignored,
 180 leaving just Student's t distribution centred on [delta].
 181
 182 This was also confirmed by experimental testing.
 183
 184 See also
 185
 186 * "Some Approximations to the Percentage Points of the Noncentral
 187 t-Distribution". C. van Eeden. International Statistical Review, 29, 4-31.
 188
 189 * "Continuous Univariate Distributions".  N.L. Johnson, S. Kotz and
 190 N. Balkrishnan. 1995. John Wiley and Sons New York.
 191
 192 The quantile is calculated via the usual
 193 __root_finding_without_derivatives method
 194 with the initial guess taken as the quantile of a normal approximation
 195 to the noncentral T.
 196
 197 There is no closed form for the mode, so this is computed via
 198 functional maximisation of the PDF.
 199
 200 The remaining functions (mean, variance etc) are implemented
 201 using the formulas given in
 202 Weisstein, Eric W. "Noncentral Student's t-Distribution."
 203 From MathWorld--A Wolfram Web Resource.
 204 [@http://mathworld.wolfram.com/NoncentralStudentst-Distribution.html
 205 http://mathworld.wolfram.com/NoncentralStudentst-Distribution.html]
 206 and in the
 207 [@http://reference.wolfram.com/mathematica/ref/NoncentralStudentTDistribution.html
 208 Mathematica documentation].
 209
 210 Some analytic properties of noncentral distributions
 211 (particularly unimodality, and monotonicity of their modes)
 212 are surveyed and summarized by:
 213
 214 Andrea van Aubel & Wolfgang Gawronski, Applied Mathematics and Computation, 141 (2003) 3-12.
 215
 216 [endsect] [/section:nc_t_dist]
 217
 218 [/ nc_t.qbk
 219   Copyright 2008, 2012 John Maddock and Paul A. Bristow.
 220   Distributed under the Boost Software License, Version 1.0.
 221   (See accompanying file LICENSE_1_0.txt or copy at
 222   http://www.boost.org/LICENSE_1_0.txt).
 223 ]
 224