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