ceph/src/boost/libs/math/doc/distributions/inverse_gaussian.qbk

   1 [section:inverse_gaussian_dist Inverse Gaussian (or Inverse Normal) Distribution]
   2
   3 ``#include <boost/math/distributions/inverse_gaussian.hpp>``
   4
   5    namespace boost{ namespace math{
   6
   7    template <class RealType = double,
   8              class ``__Policy``   = ``__policy_class`` >
   9    class inverse_gaussian_distribution
  10    {
  11    public:
  12       typedef RealType value_type;
  13       typedef Policy   policy_type;
  14
  15       inverse_gaussian_distribution(RealType mean = 1, RealType scale = 1);
  16
  17       RealType mean()const; // mean default 1.
  18       RealType scale()const; // Optional scale, default 1 (unscaled).
  19       RealType shape()const; // Shape = scale/mean.
  20    };
  21    typedef inverse_gaussian_distribution<double> inverse_gaussian;
  22
  23    }} // namespace boost // namespace math
  24
  25 The Inverse Gaussian distribution distribution is a continuous probability distribution.
  26
  27 The distribution is also called 'normal-inverse Gaussian distribution',
  28 and 'normal Inverse' distribution.
  29
  30 It is also convenient to provide unity as default for both mean and scale.
  31 This is the Standard form for all distributions.
  32 The Inverse Gaussian distribution was first studied in relation to Brownian motion.
  33 In 1956 M.C.K. Tweedie used the name Inverse Gaussian because there is an inverse relationship
  34 between the time to cover a unit distance and distance covered in unit time.
  35 The inverse Gaussian is one of family of distributions that have been called the
  36 [@http://en.wikipedia.org/wiki/Tweedie_distributions Tweedie distributions].
  37
  38 (So ['inverse] in the name may mislead: it does [*not] relate to the inverse of a distribution).
  39
  40 The tails of the distribution decrease more slowly than the normal distribution.
  41 It is therefore suitable to model phenomena
  42 where numerically large values are more probable than is the case for the normal distribution.
  43 For stock market returns and prices, a key characteristic is that it models
  44 that extremely large variations from typical (crashes) can occur
  45 even when almost all (normal) variations are small.
  46
  47 Examples are returns from financial assets and turbulent wind speeds.
  48
  49 The normal-inverse Gaussian distributions form
  50 a subclass of the generalised hyperbolic distributions.
  51
  52 See
  53 [@http://en.wikipedia.org/wiki/Normal-inverse_Gaussian_distribution distribution].
  54 [@http://mathworld.wolfram.com/InverseGaussianDistribution.html
  55   Weisstein, Eric W. "Inverse Gaussian Distribution." From MathWorld--A Wolfram Web Resource.]
  56
  57 If you want a `double` precision inverse_gaussian distribution you can use
  58
  59 ``boost::math::inverse_gaussian_distribution<>``
  60
  61 or, more conveniently, you can write
  62
  63   using boost::math::inverse_gaussian;
  64   inverse_gaussian my_ig(2, 3);
  65
  66 For mean parameters [mu] and scale (also called precision) parameter [lambda],
  67 and random variate x,
  68 the inverse_gaussian distribution is defined by the probability density function (PDF):
  69
  70 __spaces f(x;[mu], [lambda]) = [sqrt]([lambda]/2[pi]x[super 3]) e[super -[lambda](x-[mu])[sup2]/2[mu][sup2]x]
  71
  72 and Cumulative Density Function (CDF):
  73
  74 __spaces  F(x;[mu], [lambda]) = [Phi]{[sqrt]([lambda]/x) (x/[mu]-1)} + e[super 2[mu]/[lambda]] [Phi]{-[sqrt]([lambda]/[mu]) (1+x/[mu])}
  75
  76 where [Phi] is the standard normal distribution CDF.
  77
  78 The following graphs illustrate how the PDF and CDF of the inverse_gaussian distribution
  79 varies for a few values of parameters [mu] and [lambda]:
  80
  81 [graph inverse_gaussian_pdf]  [/.png or .svg]
  82
  83 [graph inverse_gaussian_cdf]
  84
  85 Tweedie also provided 3 other parameterisations where ([mu] and [lambda])
  86 are replaced by their ratio [phi] = [lambda]/[mu] and by 1/[mu]:
  87 these forms may be more suitable for Bayesian applications.
  88 These can be found on Seshadri, page 2 and are also discussed by Chhikara and Folks on page 105.
  89 Another related parameterisation, the __wald_distrib (where mean [mu] is unity) is also provided.
  90
  91 [h4 Member Functions]
  92
  93    inverse_gaussian_distribution(RealType df = 1, RealType scale = 1); // optionally scaled.
  94
  95 Constructs an inverse_gaussian distribution with [mu] mean,
  96 and scale [lambda], with both default values 1.
  97
  98 Requires that both the mean [mu] parameter and scale [lambda] are greater than zero,
  99 otherwise calls __domain_error.
 100
 101    RealType mean()const;
 102
 103 Returns the mean [mu] parameter of this distribution.
 104
 105    RealType scale()const;
 106
 107 Returns the scale [lambda] parameter of this distribution.
 108
 109 [h4 Non-member Accessors]
 110
 111 All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] that are generic to all
 112 distributions are supported: __usual_accessors.
 113
 114 The domain of the random variate is \[0,+[infin]).
 115 [note Unlike some definitions, this implementation supports a random variate
 116 equal to zero as a special case, returning zero for both pdf and cdf.]
 117
 118 [h4 Accuracy]
 119
 120 The inverse_gaussian distribution is implemented in terms of the
 121 exponential function and standard normal distribution ['N]0,1 [Phi] :
 122 refer to the accuracy data for those functions for more information.
 123 But in general, gamma (and thus inverse gamma) results are often accurate to a few epsilon,
 124 >14 decimal digits accuracy for 64-bit double.
 125
 126 [h4 Implementation]
 127
 128 In the following table [mu] is the mean parameter and
 129 [lambda] is the scale parameter of the inverse_gaussian distribution,
 130 /x/ is the random variate, /p/ is the probability and /q = 1-p/ its complement.
 131 Parameters [mu] for shape and [lambda] for scale
 132 are used for the inverse gaussian function.
 133
 134 [table
 135 [[Function] [Implementation Notes] ]
 136 [[pdf] [ [sqrt]([lambda]/ 2[pi]x[super 3]) e[super -[lambda](x - [mu])[sup2]/ 2[mu][sup2]x]]]
 137 [[cdf][ [Phi]{[sqrt]([lambda]/x) (x/[mu]-1)} + e[super 2[mu]/[lambda]] [Phi]{-[sqrt]([lambda]/[mu]) (1+x/[mu])} ]]
 138 [[cdf complement] [using complement of [Phi] above.] ]
 139 [[quantile][No closed form known. Estimated using a guess refined by Newton-Raphson iteration.]]
 140 [[quantile from the complement][No closed form known. Estimated using a guess refined by Newton-Raphson iteration.]]
 141 [[mode][[mu] {[sqrt](1+9[mu][sup2]/4[lambda][sup2])[sup2] - 3[mu]/2[lambda]} ]]
 142 [[median][No closed form analytic equation is known, but is evaluated as quantile(0.5)]]
 143 [[mean][[mu]] ]
 144 [[variance][[mu][cubed]/[lambda]] ]
 145 [[skewness][3 [sqrt] ([mu]/[lambda])] ]
 146 [[kurtosis_excess][15[mu]/[lambda]] ]
 147 [[kurtosis][12[mu]/[lambda]] ]
 148 ] [/table]
 149
 150 [h4 References]
 151
 152 #Wald, A. (1947). Sequential analysis. Wiley, NY.
 153 #The Inverse Gaussian distribution : theory, methodology, and applications, Raj S. Chhikara, J. Leroy Folks. ISBN 0824779975 (1989).
 154 #The Inverse Gaussian distribution : statistical theory and applications, Seshadri, V , ISBN - 0387986189 (pbk) (Dewey 519.2) (1998).
 155 #[@http://docs.scipy.org/doc/numpy/reference/generated/numpy.random.wald.html Numpy and Scipy Documentation].
 156 #[@http://bm2.genes.nig.ac.jp/RGM2/R_current/library/statmod/man/invgauss.html  R statmod invgauss functions].
 157 #[@http://cran.r-project.org/web/packages/SuppDists/index.html R SuppDists invGauss functions].
 158 (Note that these R implementations names differ in case).
 159 #[@http://www.statsci.org/s/invgauss.html StatSci.org invgauss help].
 160 #[@http://www.statsci.org/s/invgauss.statSci.org invgauss R source].
 161 #[@http://www.biostat.wustl.edu/archives/html/s-news/2001-12/msg00144.html pwald, qwald].
 162 #[@http://www.brighton-webs.co.uk/distributions/wald.asp Brighton Webs wald].
 163
 164 [endsect] [/section:inverse_gaussian_dist Inverse Gaussiann Distribution]
 165
 166 [/
 167   Copyright 2010 John Maddock and Paul A. Bristow.
 168   Distributed under the Boost Software License, Version 1.0.
 169   (See accompanying file LICENSE_1_0.txt or copy at
 170   http://www.boost.org/LICENSE_1_0.txt).
 171 ]