libs/math/doc/sf_and_dist/distributions/fisher.qbk

   1 [section:f_dist F Distribution]
   2
   3 ``#include <boost/math/distributions/fisher_f.hpp>``
   4
   5    namespace boost{ namespace math{
   6
   7    template <class RealType = double,
   8              class ``__Policy``   = ``__policy_class`` >
   9    class fisher_f_distribution;
  10
  11    typedef fisher_f_distribution<> fisher_f;
  12
  13    template <class RealType, class ``__Policy``>
  14    class fisher_f_distribution
  15    {
  16    public:
  17       typedef RealType value_type;
  18
  19       // Construct:
  20       fisher_f_distribution(const RealType& i, const RealType& j);
  21
  22       // Accessors:
  23       RealType degrees_of_freedom1()const;
  24       RealType degrees_of_freedom2()const;
  25    };
  26
  27    }} //namespaces
  28
  29 The F distribution is a continuous distribution that arises when testing
  30 whether two samples have the same variance.  If [chi][super 2][sub m][space] and
  31 [chi][super 2][sub n][space] are independent variates each distributed as
  32 Chi-Squared with /m/ and /n/ degrees of freedom, then the test statistic:
  33
  34 F[sub n,m][space] = ([chi][super 2][sub n][space] / n) / ([chi][super 2][sub m][space] / m)
  35
  36 Is distributed over the range \[0, [infin]\] with an F distribution, and
  37 has the PDF:
  38
  39 [equation fisher_pdf]
  40
  41 The following graph illustrates how the PDF varies depending on the
  42 two degrees of freedom parameters.
  43
  44 [graph fisher_f_pdf]
  45
  46
  47 [h4 Member Functions]
  48
  49       fisher_f_distribution(const RealType& df1, const RealType& df2);
  50
  51 Constructs an F-distribution with numerator degrees of freedom /df1/
  52 and denominator degrees of freedom /df2/.
  53
  54 Requires that /df1/ and /df2/ are both greater than zero, otherwise __domain_error
  55 is called.
  56
  57       RealType degrees_of_freedom1()const;
  58
  59 Returns the numerator degrees of freedom parameter of the distribution.
  60
  61       RealType degrees_of_freedom2()const;
  62
  63 Returns the denominator degrees of freedom parameter of the distribution.
  64
  65 [h4 Non-member Accessors]
  66
  67 All the [link math_toolkit.dist.dist_ref.nmp usual non-member accessor functions]
  68 that are generic to all distributions are supported: __usual_accessors.
  69
  70 The domain of the random variable is \[0, +[infin]\].
  71
  72 [h4 Examples]
  73
  74 Various [link math_toolkit.dist.stat_tut.weg.f_eg worked examples] are
  75 available illustrating the use of the F Distribution.
  76
  77 [h4 Accuracy]
  78
  79 The normal distribution is implemented in terms of the
  80 [link math_toolkit.special.sf_beta.ibeta_function incomplete beta function]
  81 and its [link math_toolkit.special.sf_beta.ibeta_inv_function inverses],
  82 refer to those functions for accuracy data.
  83
  84 [h4 Implementation]
  85
  86 In the following table /v1/ and /v2/ are the first and second
  87 degrees of freedom parameters of the distribution,
  88 /x/ is the random variate, /p/ is the probability, and /q = 1-p/.
  89
  90 [table
  91 [[Function][Implementation Notes]]
  92 [[pdf][The usual form of the PDF is given by:
  93
  94 [equation fisher_pdf]
  95
  96 However, that form is hard to evaluate directly without incurring problems with
  97 either accuracy or numeric overflow.
  98
  99 Direct differentiation of the CDF expressed in terms of the incomplete beta function
 100
 101 led to the following two formulas:
 102
 103 f[sub v1,v2](x) = y * __ibeta_derivative(v2 \/ 2, v1 \/ 2, v2 \/ (v2 + v1 * x))
 104
 105 with y = (v2 * v1) \/ ((v2 + v1 * x) * (v2 + v1 * x))
 106
 107 and
 108
 109 f[sub v1,v2](x) = y * __ibeta_derivative(v1 \/ 2, v2 \/ 2, v1 * x \/ (v2 + v1 * x))
 110
 111 with y = (z * v1 - x * v1 * v1) \/ z[super 2]
 112
 113 and z = v2 + v1 * x
 114
 115 The first of these is used for v1 * x > v2, otherwise the second is used.
 116
 117 The aim is to keep the /x/ argument to __ibeta_derivative away from 1 to avoid
 118 rounding error. ]]
 119 [[cdf][Using the relations:
 120
 121 p = __ibeta(v1 \/ 2, v2 \/ 2, v1 * x \/ (v2 + v1 * x))
 122
 123 and
 124
 125 p = __ibetac(v2 \/ 2, v1 \/ 2, v2 \/ (v2 + v1 * x))
 126
 127 The first is used for v1 * x > v2, otherwise the second is used.
 128
 129 The aim is to keep the /x/ argument to __ibeta well away from 1 to
 130 avoid rounding error. ]]
 131
 132 [[cdf complement][Using the relations:
 133
 134 p = __ibetac(v1 \/ 2, v2 \/ 2, v1 * x \/ (v2 + v1 * x))
 135
 136 and
 137
 138 p = __ibeta(v2 \/ 2, v1 \/ 2, v2 \/ (v2 + v1 * x))
 139
 140 The first is used for v1 * x < v2, otherwise the second is used.
 141
 142 The aim is to keep the /x/ argument to __ibeta well away from 1 to
 143 avoid rounding error. ]]
 144 [[quantile][Using the relation:
 145
 146 x = v2 * a \/ (v1 * b)
 147
 148 where:
 149
 150 a = __ibeta_inv(v1 \/ 2, v2 \/ 2, p)
 151
 152 and
 153
 154 b = 1 - a
 155
 156 Quantities /a/ and /b/ are both computed by __ibeta_inv without the
 157 subtraction implied above.]]
 158 [[quantile
 159
 160 from the complement][Using the relation:
 161
 162 x = v2 * a \/ (v1 * b)
 163
 164 where
 165
 166 a = __ibetac_inv(v1 \/ 2, v2 \/ 2, p)
 167
 168 and
 169
 170 b = 1 - a
 171
 172 Quantities /a/ and /b/ are both computed by __ibetac_inv without the
 173 subtraction implied above.]]
 174 [[mean][v2 \/ (v2 - 2)]]
 175 [[variance][2 * v2[super 2 ] * (v1 + v2 - 2) \/ (v1 * (v2 - 2) * (v2 - 2) * (v2 - 4))]]
 176 [[mode][v2 * (v1 - 2) \/ (v1 * (v2 + 2))]]
 177 [[skewness][2 * (v2 + 2 * v1 - 2) * sqrt((2 * v2 - 8) \/ (v1 * (v2 + v1 - 2))) \/ (v2 - 6)]]
 178 [[kurtosis and kurtosis excess]
 179     [Refer to, [@http://mathworld.wolfram.com/F-Distribution.html
 180     Weisstein, Eric W. "F-Distribution." From MathWorld--A Wolfram Web Resource.]  ]]
 181 ]
 182
 183 [endsect][/section:f_dist F distribution]
 184
 185 [/ fisher.qbk
 186   Copyright 2006 John Maddock and Paul A. Bristow.
 187   Distributed under the Boost Software License, Version 1.0.
 188   (See accompanying file LICENSE_1_0.txt or copy at
 189   http://www.boost.org/LICENSE_1_0.txt).
 190 ]