libs/math/doc/sf_and_dist/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 lambda:
  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 [delta]:
  49
  50 [graph nc_t_pdf]
  51
  52 [h4 Member Functions]
  53
  54       non_central_t_distribution(RealType v, RealType lambda);
  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 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.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 Errors In CDF of the Noncentral T Distribution
  85 [[Significand Size] [Platform and Compiler] [[nu],[delta] < 600]]
  86 [[53] [Win32, Visual C++ 8] [Peak=120 Mean=26 ] ]
  87 [[64] [RedHat Linux IA32, gcc-4.1.1] [Peak=121 Mean=26] ]
  88
  89 [[64] [Redhat Linux IA64, gcc-3.4.4] [Peak=122 Mean=25] ]
  90
  91 [[113] [HPUX IA64, aCC A.06.06] [Peak=115 Mean=24] ]
  92 ]
  93
  94 [caution The complexity of the current algorithm is dependent upon
  95 [delta][super 2]: consequently the time taken to evaluate the CDF
  96 increases rapidly for [delta] > 500, likewise the accuracy decreases
  97 rapidly for very large [delta].]
  98
  99 Accuracy for the quantile and PDF functions should be broadly similar,
 100 note however that the /mode/ is determined numerically and can not
 101 in principal be more accurate than the square root of machine epsilon.
 102
 103 [h4 Tests]
 104
 105 There are two sets of tests of this distribution: basic sanity checks
 106 compare this implementation to the test values given in
 107 "Computing discrete mixtures of continuous
 108 distributions: noncentral chisquare, noncentral t
 109 and the distribution of the square of the sample
 110 multiple correlation coefficient."
 111 Denise Benton, K. Krishnamoorthy,
 112 Computational Statistics & Data Analysis 43 (2003) 249-267.
 113 While accuracy checks use test data computed with this
 114 implementation and arbitary precision interval arithmetic:
 115 this test data is believed to be accurate to at least 50
 116 decimal places.
 117
 118
 119 [h4 Implementation]
 120
 121 The CDF is computed using a modification of the method
 122 described in
 123 "Computing discrete mixtures of continuous
 124 distributions: noncentral chisquare, noncentral t
 125 and the distribution of the square of the sample
 126 multiple correlation coefficient."
 127 Denise Benton, K. Krishnamoorthy,
 128 Computational Statistics & Data Analysis 43 (2003) 249-267.
 129
 130 This uses the following formula for the CDF:
 131
 132 [equation nc_t_ref2]
 133
 134 Where I[sub x](a,b) is the incomplete beta function, and
 135 [Phi](x) is the normal CDF at x.
 136
 137 Iteration starts at the largest of the Poisson weighting terms
 138 (at i = [delta][super 2] / 2) and then proceeds in both directions
 139 as per Benton and Krishnamoorthy's paper.
 140
 141 Alternatively, by considering what happens when t = [infin], we have
 142 x = 1, and therefore I[sub x](a,b) = 1 and:
 143
 144 [equation nc_t_ref3]
 145
 146 From this we can easily show that:
 147
 148 [equation nc_t_ref4]
 149
 150 and therefore we have a means to compute either the probability or its
 151 complement directly without the risk of cancellation error.  The
 152 crossover criterion for choosing whether to calculate the CDF or
 153 its complement is the same as for the
 154 __non_central_beta_distrib.
 155
 156 The PDF can be computed by a very similar method using:
 157
 158 [equation nc_t_ref5]
 159
 160 Where I[sub x][super '](a,b) is the derivative of the incomplete beta function.
 161
 162 The quantile is calculated via the usual
 163 [link math_toolkit.toolkit.internals1.roots2
 164 derivative-free root-finding techniques],
 165 with the initial guess taken as the quantile of a normal approximation
 166 to the noncentral T.
 167
 168 There is no closed form for the mode, so this is computed via
 169 functional maximisation of the PDF.
 170
 171 The remaining functions (mean, variance etc) are implemented
 172 using the formulas given in
 173 Weisstein, Eric W. "Noncentral Student's t-Distribution."
 174 From MathWorld--A Wolfram Web Resource.
 175 [@http://mathworld.wolfram.com/NoncentralStudentst-Distribution.html
 176 http://mathworld.wolfram.com/NoncentralStudentst-Distribution.html]
 177 and in the
 178 [@http://reference.wolfram.com/mathematica/ref/NoncentralStudentTDistribution.html
 179 Mathematica documentation].
 180
 181 Some analytic properties of noncentral distributions
 182 (particularly unimodality, and monotonicity of their modes)
 183 are surveyed and summarized by:
 184
 185 Andrea van Aubel & Wolfgang Gawronski, Applied Mathematics and Computation, 141 (2003) 3-12.
 186
 187 [endsect] [/section:nc_t_dist]
 188
 189 [/ nc_t.qbk
 190   Copyright 2008 John Maddock and Paul A. Bristow.
 191   Distributed under the Boost Software License, Version 1.0.
 192   (See accompanying file LICENSE_1_0.txt or copy at
 193   http://www.boost.org/LICENSE_1_0.txt).
 194 ]
 195