stdlib_stats_distribution_gamma:local:
:depth: 2
rvs_gamma - gamma distribution random variatesExperimental
The gamma distribution is a continuous probability distribution widely used in modeling waiting times, queue lengths, and other non-negative quantities. It is defined by a shape parameter (\(k\) or \(\alpha\)) that controls the distribution’s form and a rate parameter (\(\lambda\)) that controls its scale.
Without arguments, the function returns a random sample from the standard gamma distribution \(\Gamma(k=1, \lambda=1)\).
With a single argument for shape parameter, the function returns a random sample from the gamma distribution \(\Gamma(k=\text{shape}, \lambda=1)\).
With two arguments (shape, rate), the function returns a random sample from the gamma distribution \(\Gamma(k=\text{shape}, \lambda=\text{rate})\).
The optional loc parameter specifies the location (shift) of the distribution.
With three or more arguments including array_size, the function returns a rank-1 array of gamma distributed random variates.
For complex shape and rate parameters, the real and imaginary parts are sampled independently of each other.
The algorithm used for generating gamma random variates is fundamentally limited to double precision.[^1]
result = rvs_gamma([[shape] , rate , loc , array_size])
Impure elemental function
shape: optional argument has intent(in) and is a scalar of type real or complex.
If shape is real, its value must be positive. If shape is complex, both the real and imaginary components must be positive. This is the shape (or “form”) parameter \(k\) of the distribution. Default value is 1.0.
rate: optional argument has intent(in) and is a scalar of type real or complex.
If rate is real, its value must be positive. If rate is complex, both the real and imaginary components must be positive. This is the rate parameter (\lambda) (inverse of scale). Default value is 1.0.
loc: optional argument has intent(in) and is a scalar of type real or complex.
Specifies the location (shift) of the distribution with default value 0.0. The distribution support is x > loc.
array_size: optional argument has intent(in) and is a scalar of type integer with default kind.
The result is a scalar or rank-1 array with a size of array_size, and the same type as shape. If shape or rate is non-positive, the result is NaN.
```{literalinclude} ../../example/stats_distribution_gamma/example_gamma_rvs.f90 :language: fortran
## `pdf_gamma` - gamma distribution probability density function
### Status
Experimental
### Description
The probability density function (pdf) of the single real variable gamma distribution is:
$$ f(x)= \frac{\lambda^{k}}{\Gamma (k)}x^{k-1}e^{-\lambda x} ,\quad x>0,\ k>0,\ \lambda>0 $$
where \\(k\\) is the shape parameter, \\(\\lambda\\) is the rate parameter, and \\(\\Gamma(k)\\) is the gamma function.
An optional `loc` parameter specifies the location (shift) of the distribution.
For a complex variable \\(z=(x + y i)\\) with independent real \\(x\\) and imaginary \\(y\\) parts, the joint probability density function is the product of the corresponding real and imaginary marginal pdfs:[^2]
$$f(x+\mathit{i}y)=f(x)f(y)$$
### Syntax
`result = `pdf_gamma`(x, shape, rate `, loc`)`
### Class
Impure elemental function
### Arguments
`x`: has `intent(in)` and is a scalar of type `real` or `complex`. The point at which to evaluate the pdf.
`shape`: has `intent(in)` and is a scalar of type `real` or `complex`. The shape parameter \\(k\\).
If `shape` is `real`, its value must be positive. If `shape` is `complex`, both the real and imaginary components must be positive.
`rate`: has `intent(in)` and is a scalar of type `real` or `complex`. The rate parameter \\(\\lambda\\).
If `rate` is `real`, its value must be positive. If `rate` is `complex`, both the real and imaginary components must be positive.
`loc`: optional argument has `intent(in)` and is a scalar of type `real` or `complex`. The location (shift) parameter with default value 0.0.
All arguments must have the same type.
### Return value
The result is a scalar or an array, with a shape conformable to the arguments, and the same type as the input arguments. If `shape` or `rate` is non-positive, the result is `NaN`.
### Example
```{literalinclude} ../../example/stats_distribution_gamma/example_gamma_pdf.f90
:language: fortran
cdf_gamma - gamma distribution cumulative distribution functionExperimental
Cumulative distribution function (cdf) of the single real variable gamma distribution:
\[F(x)= \frac{\gamma (k, \lambda x)}{\Gamma (k)},\quad x>0,\ k>0,\ \lambda>0\]where \(\gamma(k, z)\) is the lower incomplete gamma function, and \(\Gamma(k)\) is the gamma function. This is often referred to as the regularized gamma P function.
An optional loc parameter specifies the location (shift) of the distribution.
For a complex variable \(z=(x + y i)\) with independent real \(x\) and imaginary \(y\) parts, the joint cumulative distribution function is the product of the corresponding real and imaginary marginal cdfs:[^2]
\[F(x+\mathit{i}y)=F(x)F(y)\]result = cdf_gamma(x, shape, rate , loc)
Impure elemental function
x: has intent(in) and is a scalar of type real or complex. The point at which to evaluate the cdf.
shape: has intent(in) and is a scalar of type real or complex. The shape parameter (k).
If shape is real, its value must be positive. If shape is complex, both the real and imaginary components must be positive.
rate: has intent(in) and is a scalar of type real or complex. The rate parameter (\lambda).
If rate is real, its value must be positive. If rate is complex, both the real and imaginary components must be positive.
loc: optional argument has intent(in) and is a scalar of type real or complex. The location (shift) parameter with default value 0.0.
All arguments must have the same type.
The result is a scalar or an array, with a shape conformable to the arguments, and the same type as the input arguments. If shape or rate is non-positive, the result is NaN.
```{literalinclude} ../../example/stats_distribution_gamma/example_gamma_cdf.f90 :language: fortran
[^1]: Marsaglia, George, and Wai Wan Tsang. "The ziggurat method for generating random variables." _Journal of statistical software_ 5 (2000): 1-7.
[^2]: Miller, Scott, and Donald Childers. _Probability and random processes: With applications to signal processing and communications_. Academic Press, 2012 (p. 197).