naginterfaces.library.stat.inv_​cdf_​gamma_​vector

naginterfaces.library.stat.inv_cdf_gamma_vector(tail, p, a, b, tol=0.0)

inv_cdf_gamma_vector returns a number of deviates associated with given probabilities of the gamma distribution.

For full information please refer to the NAG Library document for g01tf

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/g01/g01tff.html

Parameters

tailstr, length 1, array-like, shape $\left(\text{ltail}\right)$

Indicates which tail the supplied probabilities represent. For $j=\left(mod(\text{i}-1,\text{ltail})\right)+1-1$, for $\text{i}=1,2,\dots ,max(\text{ltail},\text{lp},\text{la},\text{lb})$:

$tail\left[j\right]=\text{'L'}$

The lower tail probability, i.e., $p_i=(G_i\le g_{p_i}:{\alpha }_i,{\beta }_i)$.

$tail\left[j\right]=\text{'U'}$

The upper tail probability, i.e., $p_i=(G_i\ge g_{p_i}:{\alpha }_i,{\beta }_i)$.

pfloat, array-like, shape $\left(\text{lp}\right)$

$p_i$, the probability of the required gamma distribution as defined by $tail$.

afloat, array-like, shape $\left(\text{la}\right)$

${\alpha }_i$, the first parameter of the required gamma distribution.

bfloat, array-like, shape $\left(\text{lb}\right)$

${\beta }_i$, the second parameter of the required gamma distribution.

tolfloat, optional

The relative accuracy required by you in the results. If inv_cdf_gamma_vector is entered with $tol$ greater than or equal to $1.0$ or less than $10\times \text{machine precision}$ (see machine.precision), the value of $10\times \text{machine precision}$ is used instead.

Returns

gfloat, ndarray, shape $(max(\text{ltail},\text{lp}))$

$g_{p_i}$, the deviates for the gamma distribution.

ivalidint, ndarray, shape $(max(\text{ltail},\text{lp}))$

$ivalid[i-1]$ indicates any errors with the input arguments, with

$ivalid[i-1]=0$

No error.

$ivalid[i-1]=1$

On entry, invalid value supplied in $tail$ when calculating $g_{p_i}$.

$ivalid[i-1]=2$

On entry, invalid value for $p_i$.

$ivalid[i-1]=3$

On entry, ${\alpha }_i\le 0.0$, or, ${\alpha }_i>{10}^6$, or, ${\beta }_i\le 0.0$.

$ivalid[i-1]=4$

$p_i$ is too close to $0.0$ or $1.0$ to enable the result to be calculated.

$ivalid[i-1]=5$

The solution has failed to converge. The result may be a reasonable approximation.

Raises

NagValueError

(errno $2$)

On entry, $\text{array size}=⟨value⟩$.

Constraint: $\text{ltail}>0$.

(errno $3$)

On entry, $\text{array size}=⟨value⟩$.

Constraint: $\text{lp}>0$.

(errno $4$)

On entry, $\text{array size}=⟨value⟩$.

Constraint: $\text{la}>0$.

(errno $5$)

On entry, $\text{array size}=⟨value⟩$.

Constraint: $\text{lb}>0$.

Warns

NagAlgorithmicWarning

(errno $1$)

On entry, at least one value of $tail$, $p$, $a$, or $b$ was invalid.

Check $ivalid$ for more information.

Notes

The deviate, $g_{p_i}$, associated with the lower tail probability, $p_i$, of the gamma distribution with shape parameter ${\alpha }_i$ and scale parameter ${\beta }_i$, is defined as the solution to

$$(G_i\le g_{p_i}:{\alpha }_i,{\beta }_i)=p_i=\frac{1}{{\beta }_i^{{\alpha }_i}\Gamma \left({\alpha }_i\right)}{\int }_0^{g_{p_i}}{e}_i^{-G_i/{\beta }_i}{G}_i^{{\alpha }_i-1}d{G}_i\text{,}0\le g_{p_i}<\infty \text{;}{\alpha }_i,{\beta }_i>0\text{.}$$

The method used is described by Best and Roberts (1975) making use of the relationship between the gamma distribution and the ${\chi }^2$-distribution.

Let $y_i=2\frac{g_{p_i}}{{\beta }_i}$. The required $y_i$ is found from the Taylor series expansion

$$y_i=y_0+\sum _r\frac{C_r\left(y_0\right)}{r!}{\left(\frac{E_i}{\varphi \left(y_0\right)}\right)}^r\text{,}$$

where $y_0$ is a starting approximation

$C_1\left(u_i\right)=1$,

$C_{r+1}\left(u_i\right)=(r\Psi +\frac{d}{d{u}_i})C_r\left(u_i\right)$,

${\Psi }_i=\frac{1}{2}-\frac{{\alpha }_i-1}{u_i}$,

$E_i=p_i-{\int }_0^{y_0}{\varphi }_i\left(u_i\right)d{u}_i$,

${\varphi }_i\left(u_i\right)=\frac{1}{2^{{\alpha }_i}\Gamma \left({\alpha }_i\right)}{e}_i^{-u_i/2}{u}_i^{{\alpha }_i-1}$.

For most values of $p_i$ and ${\alpha }_i$ the starting value

$$y_{01}=2{\alpha }_i{(z_i\sqrt{\frac{1}{9{\alpha }_i}}+1-\frac{1}{9{\alpha }_i})}^3$$

is used, where $z_i$ is the deviate associated with a lower tail probability of $p_i$ for the standard Normal distribution.

For $p_i$ close to zero,

$$y_{02}={\left(p_i{\alpha }_i{2}^{{\alpha }_i}\Gamma \left({\alpha }_i\right)\right)}^{1/{\alpha }_i}$$

is used.

For large $p_i$ values, when $y_{01}>4.4{\alpha }_i+6.0$,

$$y_{03}=-2[ln(1-p_i)-({\alpha }_i-1)ln\left(\frac{1}{2}{y}_{01}\right)+ln\left(\Gamma \left({\alpha }_i\right)\right)]$$

is found to be a better starting value than $y_{01}$.

For small ${\alpha }_i$ $({\alpha }_i\le 0.16)$, $p_i$ is expressed in terms of an approximation to the exponential integral and $y_{04}$ is found by Newton–Raphson iterations.

Seven terms of the Taylor series are used to refine the starting approximation, repeating the process if necessary until the required accuracy is obtained.

The input arrays to this function are designed to allow maximum flexibility in the supply of vector arguments by re-using elements of any arrays that are shorter than the total number of evaluations required. See the G01 Introduction for further information.

References

Best, D J and Roberts, D E, 1975, Algorithm AS 91. The percentage points of the ${\chi }^2$ distribution, Appl. Statist. (24), 385–388