libs/math/doc/distributions/nc_f.qbk

   1 [section:nc_f_dist Noncentral F Distribution]
   2
   3 ``#include <boost/math/distributions/non_central_f.hpp>``
   4
   5    namespace boost{ namespace math{
   6
   7    template <class RealType = double,
   8              class ``__Policy``   = ``__policy_class`` >
   9    class non_central_f_distribution;
  10
  11    typedef non_central_f_distribution<> non_central_f;
  12
  13    template <class RealType, class ``__Policy``>
  14    class non_central_f_distribution
  15    {
  16    public:
  17       typedef RealType  value_type;
  18       typedef Policy    policy_type;
  19
  20       // Constructor:
  21       non_central_f_distribution(RealType v1, RealType v2, RealType lambda);
  22
  23       // Accessor to degrees_of_freedom parameters v1 & v2:
  24       RealType degrees_of_freedom1()const;
  25       RealType degrees_of_freedom2()const;
  26
  27       // Accessor to non-centrality parameter lambda:
  28       RealType non_centrality()const;
  29    };
  30
  31    }} // namespaces
  32
  33 The noncentral F distribution is a generalization of the __F_distrib.
  34 It is defined as the ratio
  35
  36 [expression F = (X/v1) / (Y/v2)]
  37
  38 where X is a noncentral [chi][super 2]
  39 random variable with /v1/ degrees of freedom and non-centrality parameter [lambda],
  40 and Y is a central [chi][super 2] random variable with /v2/ degrees of freedom.
  41
  42 This gives the following PDF:
  43
  44 [equation nc_f_ref1]
  45
  46 where ['L[sub a][super b](c)] is a generalised Laguerre polynomial and ['B(a,b)] is the
  47 __beta function, or
  48
  49 [equation nc_f_ref2]
  50
  51 The following graph illustrates how the distribution changes
  52 for different values of [lambda]:
  53
  54 [graph nc_f_pdf]
  55
  56 [h4 Member Functions]
  57
  58       non_central_f_distribution(RealType v1, RealType v2, RealType lambda);
  59
  60 Constructs a non-central beta distribution with parameters /v1/ and /v2/
  61 and non-centrality parameter /lambda/.
  62
  63 Requires /v1/ > 0, /v2/ > 0 and lambda >= 0, otherwise calls __domain_error.
  64
  65       RealType degrees_of_freedom1()const;
  66
  67 Returns the parameter /v1/ from which this object was constructed.
  68
  69       RealType degrees_of_freedom2()const;
  70
  71 Returns the parameter /v2/ from which this object was constructed.
  72
  73       RealType non_centrality()const;
  74
  75 Returns the non-centrality parameter /lambda/ from which this object was constructed.
  76
  77 [h4 Non-member Accessors]
  78
  79 All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
  80 that are generic to all distributions are supported: __usual_accessors.
  81
  82 The domain of the random variable is \[0, +[infin]\].
  83
  84 [h4 Accuracy]
  85
  86 This distribution is implemented in terms of the
  87 __non_central_beta_distrib: refer to that distribution for accuracy data.
  88
  89 [h4 Tests]
  90
  91 Since this distribution is implemented by adapting another distribution,
  92 the tests consist of basic sanity checks computed by the
  93 [@http://www.r-project.org/ R-2.5.1 Math library statistical
  94 package] and its pbeta and dbeta functions.
  95
  96 [h4 Implementation]
  97
  98 In the following table /v1/ and /v2/ are the first and second
  99 degrees of freedom parameters of the distribution, [lambda]
 100 is the non-centrality parameter,
 101 /x/ is the random variate, /p/ is the probability, and /q = 1-p/.
 102
 103 [table
 104 [[Function][Implementation Notes]]
 105 [[pdf][Implemented in terms of the non-central beta PDF using the relation:
 106
 107 [role serif_italic f(x;v1,v2;[lambda]) = (v1\/v2) / ((1+y)*(1+y)) * g(y\/(1+y);v1\/2,v2\/2;[lambda])]
 108
 109 where [role serif_italic g(x; a, b; [lambda])] is the non central beta PDF, and:
 110
 111 [role serif_italic y = x * v1 \/ v2]
 112 ]]
 113 [[cdf][Using the relation:
 114
 115 [role serif_italic p = B[sub y](v1\/2, v2\/2; [lambda])]
 116
 117 where [role serif_italic B[sub x](a, b; [lambda])] is the noncentral beta distribution CDF and
 118
 119 [role serif_italic y = x * v1 \/ v2]
 120
 121 ]]
 122
 123 [[cdf complement][Using the relation:
 124
 125 [role serif_italic q = 1 - B[sub y](v1\/2, v2\/2; [lambda])]
 126
 127 where [role serif_italic 1 - B[sub x](a, b; [lambda])] is the complement of the
 128 noncentral beta distribution CDF and
 129
 130 [role serif_italic y = x * v1 \/ v2]
 131
 132 ]]
 133 [[quantile][Using the relation:
 134
 135 [role serif_italic x = (bx \/ (1-bx)) * (v1 \/ v2)]
 136
 137 where
 138
 139 [role serif_italic bx = Q[sub p][super -1](v1\/2, v2\/2; [lambda])]
 140
 141 and
 142
 143 [role serif_italic Q[sub p][super -1](v1\/2, v2\/2; [lambda])]
 144
 145 is the noncentral beta quantile.
 146
 147 ]]
 148 [[quantile
 149
 150 from the complement][
 151 Using the relation:
 152
 153 [role serif_italic x = (bx \/ (1-bx)) * (v1 \/ v2)]
 154
 155 where
 156
 157 [role serif_italic bx = QC[sub q][super -1](v1\/2, v2\/2; [lambda])]
 158
 159 and
 160
 161 [role serif_italic QC[sub q][super -1](v1\/2, v2\/2; [lambda])]
 162
 163 is the noncentral beta quantile from the complement.]]
 164 [[mean][[role serif_italic v2 * (v1 + l) \/ (v1 * (v2 - 2))]]]
 165 [[mode][By numeric maximalisation of the PDF.]]
 166 [[variance][Refer to, [@http://mathworld.wolfram.com/NoncentralF-Distribution.html
 167     Weisstein, Eric W. "Noncentral F-Distribution." From MathWorld--A Wolfram Web Resource.]  ]]
 168 [[skewness][Refer to, [@http://mathworld.wolfram.com/NoncentralF-Distribution.html
 169     Weisstein, Eric W. "Noncentral F-Distribution." From MathWorld--A Wolfram Web Resource.],
 170     and to the [@http://reference.wolfram.com/mathematica/ref/NoncentralFRatioDistribution.html
 171     Mathematica documentation]  ]]
 172 [[kurtosis and kurtosis excess]
 173     [Refer to, [@http://mathworld.wolfram.com/NoncentralF-Distribution.html
 174     Weisstein, Eric W. "Noncentral F-Distribution." From MathWorld--A Wolfram Web Resource.],
 175     and to the [@http://reference.wolfram.com/mathematica/ref/NoncentralFRatioDistribution.html
 176     Mathematica documentation]  ]]
 177 ]
 178
 179 Some analytic properties of noncentral distributions
 180 (particularly unimodality, and monotonicity of their modes)
 181 are surveyed and summarized by:
 182
 183 Andrea van Aubel & Wolfgang Gawronski, Applied Mathematics and Computation, 141 (2003) 3-12.
 184
 185 [endsect] [/section:nc_f_dist]
 186
 187 [/ nc_f.qbk
 188   Copyright 2008 John Maddock and Paul A. Bristow.
 189   Distributed under the Boost Software License, Version 1.0.
 190   (See accompanying file LICENSE_1_0.txt or copy at
 191   http://www.boost.org/LICENSE_1_0.txt).
 192 ]
 193