gammainc

Regularized incomplete gamma function

Syntax

Y = gammainc(X,A)

Y = gammainc(X,A,type)

Y = gammainc(X,A,scale)

Description

Y = gammainc(X,A) returns the regularized lower incomplete gamma function evaluated at the elements of X and A. Both X and A must be real, and A must be nonnegative.

example

Y = gammainc(X,A,type) returns the regularized lower or upper incomplete gamma function. The choices for type are 'lower' (the default) and 'upper'.

example

Y = gammainc(X,A,scale) scales the resulting regularized lower or upper incomplete gamma function to avoid underflow to zero or loss of accuracy. The choices for scale are 'scaledlower' and 'scaledupper'.

example

Examples

collapse all

Plot Regularized Lower Incomplete Gamma Function

Open Live Script

Calculate the regularized lower incomplete gamma function for $a$ = 0.5, 1, 1.5, and 2 within the interval $0 \leq x \leq 10$ . Loop over values of $a$ , evaluate the function at each one, and assign each result to a column of Y.

A = [0.5 1 1.5 2];
X = 0:0.05:10;
Y = zeros(201,4);
for i = 1:4
    Y(:,i) = gammainc(X,A(i));
end

Plot all of the functions in the same figure.

plot(X,Y)
grid on
legend('$a = 0.5$','$a = 1$','$a = 1.5$','$a = 2$','interpreter','latex')
title('Regularized lower incomplete gamma function for $a = 0.5, 1, 1.5,$ and $2$','interpreter','latex')
xlabel('$x$','interpreter','latex')
ylabel('$P(x,a)$','interpreter','latex')

Figure contains an axes object. The axes object with title Regularized lower incomplete gamma function for $a = 0.5, 1, 1.5,$ and $2$, xlabel $x$, ylabel $P(x,a)$ contains 4 objects of type line. These objects represent $a = 0.5$, $a = 1$, $a = 1.5$, $a = 2$.

Plot Regularized Upper Incomplete Gamma Function

Open Live Script

Calculate the regularized upper incomplete gamma function for $a$ = 0.5, 1, 1.5, and 2 within the interval $0 \leq x \leq 10$ . Loop over values of $a$ , evaluate the function at each one, and assign each result to a column of Y.

A = [0.5 1 1.5 2];
X = 0:0.05:10;
Y = zeros(201,4);
for i = 1:4
    Y(:,i) = gammainc(X,A(i),'upper');
end

Plot all of the functions in the same figure.

plot(X,Y)
grid on
legend('$a = 0.5$','$a = 1$','$a = 1.5$','$a = 2$','interpreter','latex');
title('Regularized upper incomplete gamma function for $a = 0.5, 1, 1.5,$ and $2$','interpreter','latex')
xlabel('$x$','interpreter','latex')
ylabel('$Q(x,a)$','interpreter','latex')

Figure contains an axes object. The axes object with title Regularized upper incomplete gamma function for $a = 0.5, 1, 1.5,$ and $2$, xlabel $x$, ylabel $Q(x,a)$ contains 4 objects of type line. These objects represent $a = 0.5$, $a = 1$, $a = 1.5$, $a = 2$.

Plot Scaled Incomplete Gamma Function

Open Live Script

Calculate the unscaled regularized lower incomplete gamma function for $a = 1$ within the interval $0 \leq x \leq 2$ . Plot the function.

a = 1;
x = 0:0.001:2;
Y = gammainc(x,a);
plot(x,Y);
xlabel('$x$','interpreter','latex');
ylabel('$P(x,1)$','interpreter','latex')
hold on

Next, calculate the scaled lower incomplete gamma function. Plot the function on the same graph. The scaled function has different asymptotic behavior near 0, which avoids underflow when $x$ is close to 0.

Ys = gammainc(x,a,'scaledlower');
plot(x,Ys,'--');
legend('unscaled','scaled')

Figure contains an axes object. The axes object with xlabel $x$, ylabel $P(x,1)$ contains 2 objects of type line. These objects represent unscaled, scaled.

Input Arguments

collapse all

`X` — Input array
scalar | vector | matrix | multidimensional array

Input array, specified as a scalar, vector, matrix, or multidimensional array. The elements of X must be real. X and A must be the same size, or else one of them must be a scalar.

Data Types: single | double

`A` — Input array
scalar | vector | matrix | multidimensional array

Input array, specified as a scalar, vector, matrix, or multidimensional array. The elements of A must be real and nonnegative. X and A must be the same size, or else one of them must be a scalar.

Data Types: single | double

`type` — Type of regularized incomplete gamma function
`'lower'` (default) | `'upper'`

Type of regularized incomplete gamma function, specified as 'lower' or 'upper'. If type is 'lower', then gammainc returns the regularized lower incomplete gamma function. If type is 'upper', then gammainc returns the regularized upper incomplete gamma function.

`scale` — Scaling option
`'scaledlower'` | `'scaledupper'`

Scaling option, specified as 'scaledlower' or 'scaledupper'. If scale is 'scaledlower' or 'scaledupper', then gammainc scales the regularized lower or upper incomplete gamma function by a factor of $Γ (a + 1) e^{x} / x^{a}$ , where $Γ (a)$ is the gamma function. This scaling cancels out the asymptotic behavior of the function near 0, which avoids underflow with small arguments.

Limitations

When x is negative, the regularized incomplete gamma function can be inaccurate for abs(x) > a+1.

More About

collapse all

Incomplete Gamma Function

The regularized lower incomplete gamma function P and the regularized upper incomplete gamma function Q are defined by

$\begin{array}{l} P (x, a) = \frac{1}{Γ (a)} \int_{0}^{x} t^{a - 1} e^{- t} d t, \\ Q (x, a) = \frac{1}{Γ (a)} \int_{x}^{\infty} t^{a - 1} e^{- t} d t . \end{array}$

The gamma function $Γ (a)$ is defined by

$Γ (a) = \int_{0}^{\infty} t^{a - 1} e^{- t} d t .$

MATLAB^® uses the regularized or normalized definition of the incomplete gamma function, where $P (x, a) + Q (x, a) = 1$ .

The scaled lower and upper incomplete gamma function are defined by

$\begin{array}{l} P_{s} (x, a) = \frac{Γ (a + 1)}{Γ (a)} \frac{e^{x}}{x^{a}} \int_{0}^{x} t^{a - 1} e^{- t} d t, \\ Q_{s} (x, a) = \frac{Γ (a + 1)}{Γ (a)} \frac{e^{x}}{x^{a}} \int_{x}^{\infty} t^{a - 1} e^{- t} d t . \end{array}$

Some properties of the regularized lower incomplete gamma function are:

$\lim_{x \to \infty} P (x, a) = 1 for a \geq 0$
$\lim_{x, a \to 0} P (x, a) = 1$

Tips

When the regularized upper incomplete gamma function is close to 0, specifying the 'upper' option to calculate the function is more accurate than subtracting the regularized lower incomplete gamma function from 1.

References

[1] Olver, F. W. J., A. B. Olde Daalhuis, D. W. Lozier, B. I. Schneider, R. F. Boisvert, C. W. Clark, B. R. Miller, and B. V. Saunders, eds., Chapter 8. Incomplete Gamma and Related Functions, NIST Digital Library of Mathematical Functions, Release 1.0.22, Mar. 15, 2018.

Extended Capabilities

Tall Arrays
Calculate with arrays that have more rows than fit in memory.

The gammainc function fully supports tall arrays. For more information, see Tall Arrays.

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

Output is always complex.
Strict single-precision calculations are not supported. In the generated code, single-precision inputs produce single-precision outputs. However, variables inside the function might be double-precision.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The gammainc function supports GPU array input with these usage notes and limitations:

The elements of X must be nonnegative.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays
Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a

gammainc

Syntax

Description

Examples

Plot Regularized Lower Incomplete Gamma Function

Plot Regularized Upper Incomplete Gamma Function

Plot Scaled Incomplete Gamma Function

Input Arguments

X — Input array scalar | vector | matrix | multidimensional array

A — Input array scalar | vector | matrix | multidimensional array

type — Type of regularized incomplete gamma function 'lower' (default) | 'upper'

scale — Scaling option 'scaledlower' | 'scaledupper'

Limitations

More About

Incomplete Gamma Function

Tips

References

Extended Capabilities

Tall Arrays Calculate with arrays that have more rows than fit in memory.

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

Thread-Based Environment Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

GPU Arrays Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Distributed Arrays Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

Version History

See Also

`X` — Input array
scalar | vector | matrix | multidimensional array

`A` — Input array
scalar | vector | matrix | multidimensional array

`type` — Type of regularized incomplete gamma function
`'lower'` (default) | `'upper'`

`scale` — Scaling option
`'scaledlower'` | `'scaledupper'`

Tall Arrays
Calculate with arrays that have more rows than fit in memory.

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Distributed Arrays
Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.