libs/math/doc/distributions/chi_squared.qbk

   1 [section:chi_squared_dist Chi Squared Distribution]
   2
   3 ``#include <boost/math/distributions/chi_squared.hpp>``
   4
   5    namespace boost{ namespace math{
   6
   7    template <class RealType = double,
   8              class ``__Policy``   = ``__policy_class`` >
   9    class chi_squared_distribution;
  10
  11    typedef chi_squared_distribution<> chi_squared;
  12
  13    template <class RealType, class ``__Policy``>
  14    class chi_squared_distribution
  15    {
  16    public:
  17       typedef RealType  value_type;
  18       typedef Policy    policy_type;
  19
  20       // Constructor:
  21       chi_squared_distribution(RealType i);
  22
  23       // Accessor to parameter:
  24       RealType degrees_of_freedom()const;
  25
  26       // Parameter estimation:
  27       static RealType find_degrees_of_freedom(
  28          RealType difference_from_mean,
  29          RealType alpha,
  30          RealType beta,
  31          RealType sd,
  32          RealType hint = 100);
  33    };
  34
  35    }} // namespaces
  36
  37 The Chi-Squared distribution is one of the most widely used distributions
  38 in statistical tests.  If [chi][sub i] are [nu]
  39 independent, normally distributed
  40 random variables with means [mu][sub i] and variances [sigma][sub i][super 2],
  41 then the random variable:
  42
  43 [equation chi_squ_ref1]
  44
  45 is distributed according to the Chi-Squared distribution.
  46
  47 The Chi-Squared distribution is a special case of the gamma distribution
  48 and has a single parameter [nu] that specifies the number of degrees of
  49 freedom.  The following graph illustrates how the distribution changes
  50 for different values of [nu]:
  51
  52 [graph chi_squared_pdf]
  53
  54 [h4 Member Functions]
  55
  56       chi_squared_distribution(RealType v);
  57
  58 Constructs a Chi-Squared distribution with /v/ degrees of freedom.
  59
  60 Requires v > 0, 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       static RealType find_degrees_of_freedom(
  67          RealType difference_from_variance,
  68          RealType alpha,
  69          RealType beta,
  70          RealType variance,
  71          RealType hint = 100);
  72
  73 Estimates the sample size required to detect a difference from a nominal
  74 variance in a Chi-Squared test for equal standard deviations.
  75
  76 [variablelist
  77 [[difference_from_variance][The difference from the assumed nominal variance
  78    that is to be detected: Note that the sign of this value is critical, see below.]]
  79 [[alpha][The maximum acceptable risk of rejecting the null hypothesis when it is
  80          in fact true.]]
  81 [[beta][The maximum acceptable risk of falsely failing to reject the null hypothesis.]]
  82 [[variance][The nominal variance being tested against.]]
  83 [[hint][An optional hint on where to start looking for a result: the current sample
  84       size would be a good choice.]]
  85 ]
  86
  87 Note that this calculation works with /variances/ and not /standard deviations/.
  88
  89 The sign of the parameter /difference_from_variance/ is important: the Chi
  90 Squared distribution is asymmetric, and the caller must decide in advance
  91 whether they are testing for a variance greater than a nominal value (positive
  92 /difference_from_variance/) or testing for a variance less than a nominal value
  93 (negative /difference_from_variance/).  If the latter, then obviously it is
  94 a requirement that `variance + difference_from_variance > 0`, since no sample
  95 can have a negative variance!
  96
  97 This procedure uses the method in Diamond, W. J. (1989).
  98 Practical Experiment Designs, Van-Nostrand Reinhold, New York.
  99
 100 See also section on Sample sizes required in
 101 [@http://www.itl.nist.gov/div898/handbook/prc/section2/prc232.htm the NIST Engineering Statistics Handbook, Section 7.2.3.2].
 102
 103 [h4 Non-member Accessors]
 104
 105 All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
 106 that are generic to all distributions are supported: __usual_accessors.
 107
 108 (We have followed the usual restriction of the mode to degrees of freedom >= 2,
 109 but note that the maximum of the pdf is actually zero for degrees of freedom from 2 down to 0,
 110 and provide an extended definition that would avoid a discontinuity in the mode
 111 as alternative code in a comment).
 112
 113 The domain of the random variable is \[0, +[infin]\].
 114
 115 [h4 Examples]
 116
 117 Various [link math_toolkit.stat_tut.weg.cs_eg worked examples]
 118 are available illustrating the use of the Chi Squared Distribution.
 119
 120 [h4 Accuracy]
 121
 122 The Chi-Squared distribution is implemented in terms of the
 123 [link math_toolkit.sf_gamma.igamma incomplete gamma functions]:
 124 please refer to the accuracy data for those functions.
 125
 126 [h4 Implementation]
 127
 128 In the following table /v/ is the number of degrees of freedom of the distribution,
 129 /x/ is the random variate, /p/ is the probability, and /q = 1-p/.
 130
 131 [table
 132 [[Function][Implementation Notes]]
 133 [[pdf][Using the relation: pdf = __gamma_p_derivative(v / 2, x / 2) / 2 ]]
 134 [[cdf][Using the relation: p = __gamma_p(v / 2, x / 2) ]]
 135 [[cdf complement][Using the relation: q = __gamma_q(v / 2, x / 2) ]]
 136 [[quantile][Using the relation: x = 2 * __gamma_p_inv(v / 2, p) ]]
 137 [[quantile from the complement][Using the relation: x = 2 * __gamma_q_inv(v / 2, p) ]]
 138 [[mean][v]]
 139 [[variance][2v]]
 140 [[mode][v - 2 (if v >= 2)]]
 141 [[skewness][2 * sqrt(2 / v) == sqrt(8 / v)]]
 142 [[kurtosis][3 + 12 / v]]
 143 [[kurtosis excess][12 / v]]
 144 ]
 145
 146 [h4 References]
 147
 148 * [@http://www.itl.nist.gov/div898/handbook/eda/section3/eda3666.htm NIST Exploratory Data Analysis]
 149 * [@http://en.wikipedia.org/wiki/Chi-square_distribution Chi-square distribution]
 150 * [@http://mathworld.wolfram.com/Chi-SquaredDistribution.html Weisstein, Eric W. "Chi-Squared Distribution." From MathWorld--A Wolfram Web Resource.]
 151
 152
 153 [endsect] [/section:chi_squared_dist Chi Squared]
 154
 155 [/ chi_squared.qbk
 156   Copyright 2006 John Maddock and Paul A. Bristow.
 157   Distributed under the Boost Software License, Version 1.0.
 158   (See accompanying file LICENSE_1_0.txt or copy at
 159   http://www.boost.org/LICENSE_1_0.txt).
 160 ]
 161