libs/math/doc/html/math_toolkit/dist_ref/dists/gamma_dist.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Gamma (and Erlang) Distribution</title>
   5 <link rel="stylesheet" href="../../../math.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="../../../index.html" title="Math Toolkit 2.11.0">
   8 <link rel="up" href="../dists.html" title="Distributions">
   9 <link rel="prev" href="f_dist.html" title="F Distribution">
  10 <link rel="next" href="geometric_dist.html" title="Geometric Distribution">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="f_dist.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="geometric_dist.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h4 class="title">
  27 <a name="math_toolkit.dist_ref.dists.gamma_dist"></a><a class="link" href="gamma_dist.html" title="Gamma (and Erlang) Distribution">Gamma (and
  28         Erlang) Distribution</a>
  29 </h4></div></div></div>
  30 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
  31 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
  32
  33 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
  34           <span class="keyword">class</span> <a class="link" href="../../../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a>   <span class="special">=</span> <a class="link" href="../../pol_ref/pol_ref_ref.html" title="Policy Class Reference">policies::policy&lt;&gt;</a> <span class="special">&gt;</span>
  35 <span class="keyword">class</span> <span class="identifier">gamma_distribution</span>
  36 <span class="special">{</span>
  37 <span class="keyword">public</span><span class="special">:</span>
  38    <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
  39    <span class="keyword">typedef</span> <span class="identifier">Policy</span>   <span class="identifier">policy_type</span><span class="special">;</span>
  40
  41    <span class="identifier">gamma_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">shape</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">scale</span> <span class="special">=</span> <span class="number">1</span><span class="special">)</span>
  42
  43    <span class="identifier">RealType</span> <span class="identifier">shape</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
  44    <span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
  45 <span class="special">};</span>
  46
  47 <span class="special">}}</span> <span class="comment">// namespaces</span>
  48 </pre>
  49 <p>
  50           The gamma distribution is a continuous probability distribution. When the
  51           shape parameter is an integer then it is known as the Erlang Distribution.
  52           It is also closely related to the Poisson and Chi Squared Distributions.
  53         </p>
  54 <p>
  55           When the shape parameter has an integer value, the distribution is the
  56           <a href="http://en.wikipedia.org/wiki/Erlang_distribution" target="_top">Erlang distribution</a>.
  57           Since this can be produced by ensuring that the shape parameter has an
  58           integer value &gt; 0, the Erlang distribution is not separately implemented.
  59         </p>
  60 <div class="note"><table border="0" summary="Note">
  61 <tr>
  62 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
  63 <th align="left">Note</th>
  64 </tr>
  65 <tr><td align="left" valign="top">
  66 <p>
  67             To avoid potential confusion with the gamma functions, this distribution
  68             does not provide the typedef:
  69           </p>
  70 <pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">gamma_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">gamma</span><span class="special">;</span></pre>
  71 <p>
  72             Instead if you want a double precision gamma distribution you can write
  73           </p>
  74 <pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">gamma_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">my_gamma</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">1</span><span class="special">);</span></pre>
  75 </td></tr>
  76 </table></div>
  77 <p>
  78           For shape parameter <span class="emphasis"><em>k</em></span> and scale parameter &#952; it is defined
  79           by the probability density function:
  80         </p>
  81 <div class="blockquote"><blockquote class="blockquote"><p>
  82             <span class="inlinemediaobject"><img src="../../../../equations/gamma_dist_ref1.svg"></span>
  83
  84           </p></blockquote></div>
  85 <p>
  86           Sometimes an alternative formulation is used: given parameters &#945; = k and
  87           &#946; = 1 / &#952;, then the distribution can be defined by the PDF:
  88         </p>
  89 <div class="blockquote"><blockquote class="blockquote"><p>
  90             <span class="inlinemediaobject"><img src="../../../../equations/gamma_dist_ref2.svg"></span>
  91
  92           </p></blockquote></div>
  93 <p>
  94           In this form the inverse scale parameter is called a <span class="emphasis"><em>rate parameter</em></span>.
  95         </p>
  96 <p>
  97           Both forms are in common usage: this library uses the first definition
  98           throughout. Therefore to construct a Gamma Distribution from a <span class="emphasis"><em>rate
  99           parameter</em></span>, you should pass the reciprocal of the rate as the
 100           scale parameter.
 101         </p>
 102 <p>
 103           The following two graphs illustrate how the PDF of the gamma distribution
 104           varies as the parameters vary:
 105         </p>
 106 <div class="blockquote"><blockquote class="blockquote"><p>
 107             <span class="inlinemediaobject"><img src="../../../../graphs/gamma1_pdf.svg" align="middle"></span>
 108
 109           </p></blockquote></div>
 110 <div class="blockquote"><blockquote class="blockquote"><p>
 111             <span class="inlinemediaobject"><img src="../../../../graphs/gamma2_pdf.svg" align="middle"></span>
 112
 113           </p></blockquote></div>
 114 <p>
 115           The <span class="bold"><strong>Erlang Distribution</strong></span> is the same as
 116           the Gamma, but with the shape parameter an integer. It is often expressed
 117           using a <span class="emphasis"><em>rate</em></span> rather than a <span class="emphasis"><em>scale</em></span>
 118           as the second parameter (remember that the rate is the reciprocal of the
 119           scale).
 120         </p>
 121 <p>
 122           Internally the functions used to implement the Gamma Distribution are already
 123           optimised for small-integer arguments, so in general there should be no
 124           great loss of performance from using a Gamma Distribution rather than a
 125           dedicated Erlang Distribution.
 126         </p>
 127 <h5>
 128 <a name="math_toolkit.dist_ref.dists.gamma_dist.h0"></a>
 129           <span class="phrase"><a name="math_toolkit.dist_ref.dists.gamma_dist.member_functions"></a></span><a class="link" href="gamma_dist.html#math_toolkit.dist_ref.dists.gamma_dist.member_functions">Member
 130           Functions</a>
 131         </h5>
 132 <pre class="programlisting"><span class="identifier">gamma_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">shape</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">scale</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
 133 </pre>
 134 <p>
 135           Constructs a gamma distribution with shape <span class="emphasis"><em>shape</em></span> and
 136           scale <span class="emphasis"><em>scale</em></span>.
 137         </p>
 138 <p>
 139           Requires that the shape and scale parameters are greater than zero, otherwise
 140           calls <a class="link" href="../../error_handling.html#math_toolkit.error_handling.domain_error">domain_error</a>.
 141         </p>
 142 <pre class="programlisting"><span class="identifier">RealType</span> <span class="identifier">shape</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
 143 </pre>
 144 <p>
 145           Returns the <span class="emphasis"><em>shape</em></span> parameter of this distribution.
 146         </p>
 147 <pre class="programlisting"><span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
 148 </pre>
 149 <p>
 150           Returns the <span class="emphasis"><em>scale</em></span> parameter of this distribution.
 151         </p>
 152 <h5>
 153 <a name="math_toolkit.dist_ref.dists.gamma_dist.h1"></a>
 154           <span class="phrase"><a name="math_toolkit.dist_ref.dists.gamma_dist.non_member_accessors"></a></span><a class="link" href="gamma_dist.html#math_toolkit.dist_ref.dists.gamma_dist.non_member_accessors">Non-member
 155           Accessors</a>
 156         </h5>
 157 <p>
 158           All the <a class="link" href="../nmp.html" title="Non-Member Properties">usual non-member accessor
 159           functions</a> that are generic to all distributions are supported:
 160           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.cdf">Cumulative Distribution Function</a>,
 161           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.pdf">Probability Density Function</a>,
 162           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.quantile">Quantile</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.hazard">Hazard Function</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.chf">Cumulative Hazard Function</a>,
 163           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.mean">mean</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.median">median</a>,
 164           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.mode">mode</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.variance">variance</a>,
 165           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.sd">standard deviation</a>,
 166           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.skewness">skewness</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.kurtosis">kurtosis</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.kurtosis_excess">kurtosis_excess</a>,
 167           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.range">range</a> and <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.support">support</a>.
 168         </p>
 169 <p>
 170           The domain of the random variable is [0,+&#8734;].
 171         </p>
 172 <h5>
 173 <a name="math_toolkit.dist_ref.dists.gamma_dist.h2"></a>
 174           <span class="phrase"><a name="math_toolkit.dist_ref.dists.gamma_dist.accuracy"></a></span><a class="link" href="gamma_dist.html#math_toolkit.dist_ref.dists.gamma_dist.accuracy">Accuracy</a>
 175         </h5>
 176 <p>
 177           The gamma distribution is implemented in terms of the incomplete gamma
 178           functions <a class="link" href="../../sf_gamma/igamma.html" title="Incomplete Gamma Functions">gamma_p</a> and
 179           <a class="link" href="../../sf_gamma/igamma.html" title="Incomplete Gamma Functions">gamma_q</a> and their inverses
 180           <a class="link" href="../../sf_gamma/igamma_inv.html" title="Incomplete Gamma Function Inverses">gamma_p_inv</a> and
 181           <a class="link" href="../../sf_gamma/igamma_inv.html" title="Incomplete Gamma Function Inverses">gamma_q_inv</a>: refer
 182           to the accuracy data for those functions for more information.
 183         </p>
 184 <h5>
 185 <a name="math_toolkit.dist_ref.dists.gamma_dist.h3"></a>
 186           <span class="phrase"><a name="math_toolkit.dist_ref.dists.gamma_dist.implementation"></a></span><a class="link" href="gamma_dist.html#math_toolkit.dist_ref.dists.gamma_dist.implementation">Implementation</a>
 187         </h5>
 188 <p>
 189           In the following table <span class="emphasis"><em>k</em></span> is the shape parameter of
 190           the distribution, &#952; is its scale parameter, <span class="emphasis"><em>x</em></span> is the
 191           random variate, <span class="emphasis"><em>p</em></span> is the probability and <span class="emphasis"><em>q
 192           = 1-p</em></span>.
 193         </p>
 194 <div class="informaltable"><table class="table">
 195 <colgroup>
 196 <col>
 197 <col>
 198 </colgroup>
 199 <thead><tr>
 200 <th>
 201                   <p>
 202                     Function
 203                   </p>
 204                 </th>
 205 <th>
 206                   <p>
 207                     Implementation Notes
 208                   </p>
 209                 </th>
 210 </tr></thead>
 211 <tbody>
 212 <tr>
 213 <td>
 214                   <p>
 215                     pdf
 216                   </p>
 217                 </td>
 218 <td>
 219                   <p>
 220                     Using the relation: pdf = <a class="link" href="../../sf_gamma/gamma_derivatives.html" title="Derivative of the Incomplete Gamma Function">gamma_p_derivative</a>(k,
 221                     x / &#952;) / &#952;
 222                   </p>
 223                 </td>
 224 </tr>
 225 <tr>
 226 <td>
 227                   <p>
 228                     cdf
 229                   </p>
 230                 </td>
 231 <td>
 232                   <p>
 233                     Using the relation: p = <a class="link" href="../../sf_gamma/igamma.html" title="Incomplete Gamma Functions">gamma_p</a>(k,
 234                     x / &#952;)
 235                   </p>
 236                 </td>
 237 </tr>
 238 <tr>
 239 <td>
 240                   <p>
 241                     cdf complement
 242                   </p>
 243                 </td>
 244 <td>
 245                   <p>
 246                     Using the relation: q = <a class="link" href="../../sf_gamma/igamma.html" title="Incomplete Gamma Functions">gamma_q</a>(k,
 247                     x / &#952;)
 248                   </p>
 249                 </td>
 250 </tr>
 251 <tr>
 252 <td>
 253                   <p>
 254                     quantile
 255                   </p>
 256                 </td>
 257 <td>
 258                   <p>
 259                     Using the relation: x = &#952; * <a class="link" href="../../sf_gamma/igamma_inv.html" title="Incomplete Gamma Function Inverses">gamma_p_inv</a>(k,
 260                     p)
 261                   </p>
 262                 </td>
 263 </tr>
 264 <tr>
 265 <td>
 266                   <p>
 267                     quantile from the complement
 268                   </p>
 269                 </td>
 270 <td>
 271                   <p>
 272                     Using the relation: x = &#952;* <a class="link" href="../../sf_gamma/igamma_inv.html" title="Incomplete Gamma Function Inverses">gamma_q_inv</a>(k,
 273                     p)
 274                   </p>
 275                 </td>
 276 </tr>
 277 <tr>
 278 <td>
 279                   <p>
 280                     mean
 281                   </p>
 282                 </td>
 283 <td>
 284                   <p>
 285                     k&#952;
 286                   </p>
 287                 </td>
 288 </tr>
 289 <tr>
 290 <td>
 291                   <p>
 292                     variance
 293                   </p>
 294                 </td>
 295 <td>
 296                   <p>
 297                     k&#952;<sup>2</sup>
 298                   </p>
 299                 </td>
 300 </tr>
 301 <tr>
 302 <td>
 303                   <p>
 304                     mode
 305                   </p>
 306                 </td>
 307 <td>
 308                   <p>
 309                     (k-1)&#952; for <span class="emphasis"><em>k&gt;1</em></span> otherwise a <a class="link" href="../../error_handling.html#math_toolkit.error_handling.domain_error">domain_error</a>
 310                   </p>
 311                 </td>
 312 </tr>
 313 <tr>
 314 <td>
 315                   <p>
 316                     skewness
 317                   </p>
 318                 </td>
 319 <td>
 320                   <p>
 321                     2 / sqrt(k)
 322                   </p>
 323                 </td>
 324 </tr>
 325 <tr>
 326 <td>
 327                   <p>
 328                     kurtosis
 329                   </p>
 330                 </td>
 331 <td>
 332                   <p>
 333                     3 + 6 / k
 334                   </p>
 335                 </td>
 336 </tr>
 337 <tr>
 338 <td>
 339                   <p>
 340                     kurtosis excess
 341                   </p>
 342                 </td>
 343 <td>
 344                   <p>
 345                     6 / k
 346                   </p>
 347                 </td>
 348 </tr>
 349 </tbody>
 350 </table></div>
 351 </div>
 352 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 353 <td align="left"></td>
 354 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2019 Nikhar
 355       Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
 356       Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
 357       R&#229;de, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
 358       Daryle Walker and Xiaogang Zhang<p>
 359         Distributed under the Boost Software License, Version 1.0. (See accompanying
 360         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 361       </p>
 362 </div></td>
 363 </tr></table>
 364 <hr>
 365 <div class="spirit-nav">
 366 <a accesskey="p" href="f_dist.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="geometric_dist.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 367 </div>
 368 </body>
 369 </html>