libs/math/doc/distributions/inverse_gamma.qbk

   1 [section:inverse_gamma_dist Inverse Gamma Distribution]
   2
   3 ``#include <boost/math/distributions/inverse_gamma.hpp>``
   4
   5    namespace boost{ namespace math{
   6
   7    template <class RealType = double,
   8              class ``__Policy``   = ``__policy_class`` >
   9    class inverse_gamma_distribution
  10    {
  11    public:
  12       typedef RealType value_type;
  13       typedef Policy   policy_type;
  14
  15       inverse_gamma_distribution(RealType shape, RealType scale = 1)
  16
  17       RealType shape()const;
  18       RealType scale()const;
  19    };
  20
  21    }} // namespaces
  22
  23 The inverse_gamma distribution is a continuous probability distribution
  24 of the reciprocal of a variable distributed according to the gamma distribution.
  25
  26 The inverse_gamma distribution is used in Bayesian statistics.
  27
  28 See [@http://en.wikipedia.org/wiki/Inverse-gamma_distribution inverse gamma distribution].
  29
  30 [@http://rss.acs.unt.edu/Rdoc/library/pscl/html/igamma.html R inverse gamma distribution functions].
  31
  32 [@http://reference.wolfram.com/mathematica/ref/InverseGammaDistribution.html Wolfram inverse gamma distribution].
  33
  34 See also __gamma_distrib.
  35
  36 [note
  37 In spite of potential confusion with the inverse gamma function, this
  38 distribution *does* provide the typedef:
  39
  40 ``typedef inverse_gamma_distribution<double> gamma;``
  41
  42 If you want a `double` precision gamma distribution you can use
  43
  44 ``boost::math::inverse_gamma_distribution<>``
  45
  46 or you can write `inverse_gamma my_ig(2, 3);`]
  47
  48 For shape parameter [alpha] and scale parameter [beta], it is defined
  49 by the probability density function (PDF):
  50
  51 [expression f(x;[alpha], [beta]) = [beta][super [alpha]] * (1/x) [super [alpha]+1] exp(-[beta]/x) / [Gamma]([alpha])]
  52
  53 and cumulative density function (CDF)
  54
  55 [expression F(x;[alpha], [beta]) = [Gamma]([alpha], [beta]/x) / [Gamma]([alpha])]
  56
  57 The following graphs illustrate how the PDF and CDF of the inverse gamma distribution
  58 varies as the parameters vary:
  59
  60 [graph inverse_gamma_pdf]  [/png or svg]
  61
  62 [graph inverse_gamma_cdf]
  63
  64 [h4 Member Functions]
  65
  66    inverse_gamma_distribution(RealType shape = 1, RealType scale = 1);
  67
  68 Constructs an inverse gamma distribution with shape [alpha] and scale [beta].
  69
  70 Requires that the shape and scale parameters are greater than zero, otherwise calls
  71 __domain_error.
  72
  73    RealType shape()const;
  74
  75 Returns the [alpha] shape parameter of this inverse gamma distribution.
  76
  77    RealType scale()const;
  78
  79 Returns the [beta] scale parameter of this inverse gamma distribution.
  80
  81 [h4 Non-member Accessors]
  82
  83 All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] that are generic to all
  84 distributions are supported: __usual_accessors.
  85
  86 The domain of the random variate is \[0,+[infin]\].
  87 [note Unlike some definitions, this implementation supports a random variate
  88 equal to zero as a special case, returning zero for pdf and cdf.]
  89
  90 [h4 Accuracy]
  91
  92 The inverse gamma distribution is implemented in terms of the
  93 incomplete gamma functions __gamma_p and __gamma_q and their
  94 inverses __gamma_p_inv and __gamma_q_inv: refer to the accuracy
  95 data for those functions for more information.
  96 But in general, inverse_gamma results are accurate to a few epsilon,
  97 >14 decimal digits accuracy for 64-bit double.
  98
  99 [h4 Implementation]
 100
 101 In the following table [alpha] is the shape parameter of the distribution,
 102 [alpha] is its scale parameter, /x/ is the random variate, /p/ is the probability
 103 and /q = 1-p/.
 104
 105 [table
 106 [[Function][Implementation Notes]]
 107 [[pdf][Using the relation: pdf = __gamma_p_derivative([alpha], [beta]/ x, [beta]) / x * x ]]
 108 [[cdf][Using the relation: p = __gamma_q([alpha], [beta] / x) ]]
 109 [[cdf complement][Using the relation: q = __gamma_p([alpha], [beta] / x) ]]
 110 [[quantile][Using the relation: x = [beta]/ __gamma_q_inv([alpha], p) ]]
 111 [[quantile from the complement][Using the relation: x = [alpha]/ __gamma_p_inv([alpha], q) ]]
 112 [[mode][[beta] / ([alpha] + 1) ]]
 113 [[median][no analytic equation is known, but is evaluated as quantile(0.5)]]
 114 [[mean][[beta] / ([alpha] - 1) for [alpha] > 1, else a __domain_error]]
 115 [[variance][([beta] * [beta]) / (([alpha] - 1) * ([alpha] - 1) * ([alpha] - 2)) for [alpha] >2, else a __domain_error]]
 116 [[skewness][4 * sqrt ([alpha] -2) / ([alpha] -3) for [alpha] >3, else a __domain_error]]
 117 [[kurtosis_excess][(30 * [alpha] - 66) / (([alpha]-3)*([alpha] - 4)) for [alpha] >4, else a __domain_error]]
 118 ] [/table]
 119
 120 [endsect] [/section:inverse_gamma_dist Inverse Gamma Distribution]
 121
 122 [/
 123   Copyright 2010 John Maddock and Paul A. Bristow.
 124   Distributed under the Boost Software License, Version 1.0.
 125   (See accompanying file LICENSE_1_0.txt or copy at
 126   http://www.boost.org/LICENSE_1_0.txt).
 127 ]
 128