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

   1 [section:gamma_dist Gamma (and Erlang) Distribution]
   2
   3 ``#include <boost/math/distributions/gamma.hpp>``
   4
   5    namespace boost{ namespace math{
   6
   7    template <class RealType = double,
   8              class ``__Policy``   = ``__policy_class`` >
   9    class gamma_distribution
  10    {
  11    public:
  12       typedef RealType value_type;
  13       typedef Policy   policy_type;
  14
  15       gamma_distribution(RealType shape, RealType scale = 1)
  16
  17       RealType shape()const;
  18       RealType scale()const;
  19    };
  20
  21    }} // namespaces
  22
  23 The gamma distribution is a continuous probability distribution.
  24 When the shape parameter is an integer then it is known as the
  25 Erlang Distribution.  It is also closely related to the Poisson
  26 and Chi Squared Distributions.
  27
  28 When the shape parameter has an integer value, the distribution is the
  29 [@http://en.wikipedia.org/wiki/Erlang_distribution Erlang distribution].
  30 Since this can be produced by ensuring that the shape parameter has an
  31 integer value > 0, the Erlang distribution is not separately implemented.
  32
  33 [note
  34 To avoid potential confusion with the gamma functions, this
  35 distribution does not provide the typedef:
  36
  37 ``typedef gamma_distribution<double> gamma;``
  38
  39 Instead if you want a double precision gamma distribution you can write
  40
  41 ``boost::math::gamma_distribution<> my_gamma(1, 1);``
  42 ]
  43
  44 For shape parameter /k/ and scale parameter [theta][space] it is defined by the
  45 probability density function:
  46
  47 [equation gamma_dist_ref1]
  48
  49 Sometimes an alternative formulation is used: given parameters
  50 [alpha][space]= k and [beta][space]= 1 / [theta], then the
  51 distribution can be defined by the PDF:
  52
  53 [equation gamma_dist_ref2]
  54
  55 In this form the inverse scale parameter is called a /rate parameter/.
  56
  57 Both forms are in common usage: this library uses the first definition
  58 throughout.  Therefore to construct a Gamma Distribution from a ['rate
  59 parameter], you should pass the reciprocal of the rate as the scale parameter.
  60
  61 The following two graphs illustrate how the PDF of the gamma distribution
  62 varies as the parameters vary:
  63
  64 [graph gamma1_pdf]
  65
  66 [graph gamma2_pdf]
  67
  68 The [*Erlang Distribution] is the same as the Gamma, but with the shape parameter
  69 an integer.  It is often expressed using a /rate/ rather than a /scale/ as the
  70 second parameter (remember that the rate is the reciprocal of the scale).
  71
  72 Internally the functions used to implement the Gamma Distribution are
  73 already optimised for small-integer arguments, so in general there should
  74 be no great loss of performance from using a Gamma Distribution rather than
  75 a dedicated Erlang Distribution.
  76
  77 [h4 Member Functions]
  78
  79    gamma_distribution(RealType shape, RealType scale = 1);
  80
  81 Constructs a gamma distribution with shape /shape/ and
  82 scale /scale/.
  83
  84 Requires that the shape and scale parameters are greater than zero, otherwise calls
  85 __domain_error.
  86
  87    RealType shape()const;
  88
  89 Returns the /shape/ parameter of this distribution.
  90
  91    RealType scale()const;
  92
  93 Returns the /scale/ parameter of this distribution.
  94
  95 [h4 Non-member Accessors]
  96
  97 All the [link math_toolkit.dist.dist_ref.nmp usual non-member accessor functions] that are generic to all
  98 distributions are supported: __usual_accessors.
  99
 100 The domain of the random variable is \[0,+[infin]\].
 101
 102 [h4 Accuracy]
 103
 104 The lognormal distribution is implemented in terms of the
 105 incomplete gamma functions __gamma_p and __gamma_q and their
 106 inverses __gamma_p_inv and __gamma_q_inv: refer to the accuracy
 107 data for those functions for more information.
 108
 109 [h4 Implementation]
 110
 111 In the following table /k/ is the shape parameter of the distribution,
 112 [theta][space] is its scale parameter, /x/ is the random variate, /p/ is the probability
 113 and /q = 1-p/.
 114
 115 [table
 116 [[Function][Implementation Notes]]
 117 [[pdf][Using the relation: pdf = __gamma_p_derivative(k, x / [theta]) / [theta] ]]
 118 [[cdf][Using the relation: p = __gamma_p(k, x / [theta]) ]]
 119 [[cdf complement][Using the relation: q = __gamma_q(k, x / [theta]) ]]
 120 [[quantile][Using the relation: x = [theta][space]* __gamma_p_inv(k, p) ]]
 121 [[quantile from the complement][Using the relation: x = [theta][space]* __gamma_q_inv(k, p) ]]
 122 [[mean][k[theta] ]]
 123 [[variance][k[theta][super 2] ]]
 124 [[mode][(k-1)[theta][space] for ['k>1] otherwise a __domain_error ]]
 125 [[skewness][2 / sqrt(k) ]]
 126 [[kurtosis][3 + 6 / k]]
 127 [[kurtosis excess][6 / k ]]
 128 ]
 129
 130 [endsect][/section:gamma_dist Gamma (and Erlang) Distribution]
 131
 132
 133 [/
 134   Copyright 2006, 2010 John Maddock and Paul A. Bristow.
 135   Distributed under the Boost Software License, Version 1.0.
 136   (See accompanying file LICENSE_1_0.txt or copy at
 137   http://www.boost.org/LICENSE_1_0.txt).
 138 ]
 139