libs/math/doc/distributions/inverse_chi_squared.qbk

   1 [section:inverse_chi_squared_dist Inverse Chi Squared Distribution]
   2
   3 ``#include <boost/math/distributions/inverse_chi_squared.hpp>``
   4
   5    namespace boost{ namespace math{
   6
   7    template <class RealType = double,
   8              class ``__Policy``   = ``__policy_class`` >
   9    class inverse_chi_squared_distribution
  10    {
  11    public:
  12       typedef RealType value_type;
  13       typedef Policy   policy_type;
  14
  15       inverse_chi_squared_distribution(RealType df = 1); // Not explicitly scaled, default 1/df.
  16       inverse_chi_squared_distribution(RealType df, RealType scale = 1/df);  // Scaled.
  17
  18       RealType degrees_of_freedom()const; // Default 1.
  19       RealType scale()const; // Optional scale [xi] (variance), default 1/degrees_of_freedom.
  20    };
  21
  22    }} // namespace boost // namespace math
  23
  24 The inverse chi squared distribution is a continuous probability distribution
  25 of the *reciprocal* of a variable distributed according to the chi squared distribution.
  26
  27 The sources below give confusingly different formulae
  28 using different symbols for the distribution pdf,
  29 but they are all the same, or related by a change of variable, or choice of scale.
  30
  31 Two constructors are available to implement both the scaled and (implicitly) unscaled versions.
  32
  33 The main version has an explicit scale parameter which implements the
  34 [@http://en.wikipedia.org/wiki/Scaled-inverse-chi-square_distribution scaled inverse chi_squared distribution].
  35
  36 A second version has an implicit scale = 1/degrees of freedom and gives the 1st definition in the
  37 [@http://en.wikipedia.org/wiki/Inverse-chi-square_distribution Wikipedia inverse chi_squared distribution].
  38 The 2nd Wikipedia inverse chi_squared distribution definition can be implemented
  39 by  explicitly specifying a scale = 1.
  40
  41 Both definitions are also available in __Mathematica and in __R (geoR) with default scale = 1/degrees of freedom.
  42
  43 See
  44
  45 * Inverse chi_squared distribution [@http://en.wikipedia.org/wiki/Inverse-chi-square_distribution]
  46 * Scaled inverse chi_squared distribution[@http://en.wikipedia.org/wiki/Scaled-inverse-chi-square_distribution]
  47 * R inverse chi_squared distribution functions [@http://hosho.ees.hokudai.ac.jp/~kubo/Rdoc/library/geoR/html/InvChisquare.html R ]
  48 * Inverse chi_squared distribution functions [@http://mathworld.wolfram.com/InverseChi-SquaredDistribution.html Weisstein, Eric W. "Inverse Chi-Squared Distribution." From MathWorld--A Wolfram Web Resource.]
  49 * Inverse chi_squared distribution reference [@http://reference.wolfram.com/mathematica/ref/InverseChiSquareDistribution.html Weisstein, Eric W. "Inverse Chi-Squared Distribution reference." From Wolfram Mathematica.]
  50
  51 The inverse_chi_squared distribution is used in
  52 [@http://en.wikipedia.org/wiki/Bayesian_statistics Bayesian statistics]:
  53 the scaled inverse chi-square is conjugate prior for the normal distribution
  54 with known mean, model parameter [sigma][pow2] (variance).
  55
  56 See [@http://en.wikipedia.org/wiki/Conjugate_prior conjugate priors including a table of distributions and their priors.]
  57
  58 See also __inverse_gamma_distrib and __chi_squared_distrib.
  59
  60 The inverse_chi_squared distribution is a special case of a inverse_gamma distribution
  61 with [nu] (degrees_of_freedom) shape ([alpha]) and scale ([beta]) where
  62
  63 [expression [alpha]= [nu] /2 and [beta] = [frac12]]
  64
  65 [note This distribution *does* provide the typedef:
  66
  67 ``typedef inverse_chi_squared_distribution<double> inverse_chi_squared;``
  68
  69 If you want a `double` precision inverse_chi_squared distribution you can use
  70
  71 ``boost::math::inverse_chi_squared_distribution<>``
  72
  73 or you can write `inverse_chi_squared my_invchisqr(2, 3);`]
  74
  75 For degrees of freedom parameter [nu],
  76 the (*unscaled*) inverse chi_squared distribution is defined by the probability density function (PDF):
  77
  78 [expression f(x;[nu]) = 2[super -[nu]/2] x[super -[nu]/2-1] e[super -1/2x] / [Gamma]([nu]/2)]
  79
  80 and Cumulative Density Function (CDF)
  81
  82 [expression F(x;[nu]) = [Gamma]([nu]/2, 1/2x) / [Gamma]([nu]/2)]
  83
  84 For degrees of freedom parameter [nu] and scale parameter [xi],
  85 the *scaled* inverse chi_squared distribution is defined by the probability density function (PDF):
  86
  87 [expression f(x;[nu], [xi]) = ([xi][nu]/2)[super [nu]/2] e[super -[nu][xi]/2x] x[super -1-[nu]/2] / [Gamma]([nu]/2)]
  88
  89 and Cumulative Density Function (CDF)
  90
  91 [expression  F(x;[nu], [xi]) = [Gamma]([nu]/2, [nu][xi]/2x) / [Gamma]([nu]/2)]
  92
  93 The following graphs illustrate how the PDF and CDF of the inverse chi_squared distribution
  94 varies for a few values of parameters [nu] and [xi]:
  95
  96 [graph inverse_chi_squared_pdf]  [/.png or .svg]
  97
  98 [graph inverse_chi_squared_cdf]
  99
 100 [h4 Member Functions]
 101
 102    inverse_chi_squared_distribution(RealType df = 1); // Implicitly scaled 1/df.
 103    inverse_chi_squared_distribution(RealType df = 1, RealType scale); // Explicitly scaled.
 104
 105 Constructs an inverse chi_squared distribution with [nu] degrees of freedom ['df],
 106 and scale ['scale] with default value 1\/df.
 107
 108 Requires that the degrees of freedom [nu] parameter is greater than zero, otherwise calls
 109 __domain_error.
 110
 111    RealType degrees_of_freedom()const;
 112
 113 Returns the degrees_of_freedom [nu] parameter of this distribution.
 114
 115    RealType scale()const;
 116
 117 Returns the scale [xi] parameter of this distribution.
 118
 119 [h4 Non-member Accessors]
 120
 121 All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] that are generic to all
 122 distributions are supported: __usual_accessors.
 123
 124 The domain of the random variate is \[0,+[infin]\].
 125 [note Unlike some definitions, this implementation supports a random variate
 126 equal to zero as a special case, returning zero for both pdf and cdf.]
 127
 128 [h4 Accuracy]
 129
 130 The inverse gamma distribution is implemented in terms of the
 131 incomplete gamma functions like the __inverse_gamma_distrib that use
 132 __gamma_p and __gamma_q and their inverses __gamma_p_inv and __gamma_q_inv:
 133 refer to the accuracy data for those functions for more information.
 134 But in general, gamma (and thus inverse gamma) results are often accurate to a few epsilon,
 135 >14 decimal digits accuracy for 64-bit double.
 136 unless iteration is involved, as for the estimation of degrees of freedom.
 137
 138 [h4 Implementation]
 139
 140 In the following table [nu] is the degrees of freedom parameter and
 141 [xi] is the scale parameter of the distribution,
 142 /x/ is the random variate, /p/ is the probability and /q = 1-p/ its complement.
 143 Parameters [alpha] for shape and [beta] for scale
 144 are used for the inverse gamma function: [alpha] = [nu]/2 and [beta] = [nu] * [xi]/2.
 145
 146 [table
 147 [[Function][Implementation Notes]]
 148 [[pdf][Using the relation: pdf = __gamma_p_derivative([alpha], [beta]/ x, [beta]) / x * x ]]
 149 [[cdf][Using the relation: p = __gamma_q([alpha], [beta] / x) ]]
 150 [[cdf complement][Using the relation: q = __gamma_p([alpha], [beta] / x) ]]
 151 [[quantile][Using the relation: x = [beta]/ __gamma_q_inv([alpha], p) ]]
 152 [[quantile from the complement][Using the relation: x = [alpha]/ __gamma_p_inv([alpha], q) ]]
 153 [[mode][[nu] * [xi] / ([nu] + 2) ]]
 154 [[median][no closed form analytic equation is known, but is evaluated as quantile(0.5)]]
 155 [[mean][[nu][xi] / ([nu] - 2) for [nu] > 2, else a __domain_error]]
 156 [[variance][2 [nu][pow2] [xi][pow2] / (([nu] -2)[pow2] ([nu] -4)) for [nu] >4, else a __domain_error]]
 157 [[skewness][4 [sqrt]2 [sqrt]([nu]-4) /([nu]-6) for [nu] >6, else a __domain_error ]]
 158 [[kurtosis_excess][12 * (5[nu] - 22) / (([nu] - 6) * ([nu] - 8)) for [nu] >8, else a __domain_error]]
 159 [[kurtosis][3 + 12 * (5[nu] - 22) / (([nu] - 6) * ([nu]-8)) for [nu] >8, else a __domain_error]]
 160 ] [/table]
 161
 162 [h4 References]
 163
 164 # Bayesian Data Analysis, Andrew Gelman, John B. Carlin, Hal S. Stern, Donald B. Rubin,
 165 ISBN-13: 978-1584883883, Chapman & Hall; 2 edition (29 July 2003).
 166
 167 # Bayesian Computation with R, Jim Albert, ISBN-13: 978-0387922973, Springer; 2nd ed. edition (10 Jun 2009)
 168
 169 [endsect] [/section:inverse_chi_squared_dist Inverse chi_squared Distribution]
 170
 171 [/
 172   Copyright 2010 John Maddock and Paul A. Bristow.
 173   Distributed under the Boost Software License, Version 1.0.
 174   (See accompanying file LICENSE_1_0.txt or copy at
 175   http://www.boost.org/LICENSE_1_0.txt).
 176 ]