beta_gamma {zipfR}

Incomplete Beta and Gamma Functions (zipfR)

Description

The functions documented here compute incomplete and regularized Beta and Gamma functions as well as their logarithms and the corresponding inverse functions. These functions will be of interest to developers, not users of the toolkit.

Usage

  Cgamma(a, log=!missing(base), base=exp(1))
  Igamma(a, x, lower=TRUE, log=!missing(base), base=exp(1))
  Igamma.inv(a, y, lower=TRUE, log=!missing(base), base=exp(1))
  Rgamma(a, x, lower=TRUE, log=!missing(base), base=exp(1))
  Rgamma.inv(a, y, lower=TRUE, log=!missing(base), base=exp(1))

  Cbeta(a, b, log=!missing(base), base=exp(1))
  Ibeta(x, a, b, lower=TRUE, log=!missing(base), base=exp(1))
  Ibeta.inv(y, a, b, lower=TRUE, log=!missing(base), base=exp(1))
  Rbeta(x, a, b, lower=TRUE, log=!missing(base), base=exp(1))
  Rbeta.inv(y, a, b, lower=TRUE, log=!missing(base), base=exp(1))

Arguments

a, b

non-negative numeric vectors, the parameters of the Gamma and Beta functions (b applies only to Beta functions)

x

a non-negative numeric vector, the point at which the incomplete or regularized Gamma or Beta function is evaluated (for the Beta functions, x must be in the range [0,1]

y

a non-negative numeric vector, the values of the Gamma or Beta function on linear or logarithmic scale

lower

whether to compute the lower (TRUE) or upper (FALSE) incomplete or regularized Gamma or Beta function

log

if TRUE, return values of the Gamma and Beta functions – as well as the y argument of the inverse functions – are on logarithmic scale

base

a positive number, specifying the base of the logarithmic scale for values of the Gamma and Beta functions (default: natural logarithm). Setting the base parameter implies log=TRUE.

Value

Cgamma returns the (complete) Gamma function evaluated at a, \Gamma(a). Igamma returns the (lower or upper) incomplete Gamma function with parameter a evaluated at point x, \gamma(a,x) (lower=TRUE) or \Gamma(a,x) (lower=FALSE). Rgamma returns the corresponding regularized Gamma function, P(a,x) (lower=TRUE) or Q(a,x) (lower=FALSE). If log=TRUE, the returned values are on logarithmic scale as specified by the base parameter.

Igamma.inv and Rgamma.inv compute the inverse of the incomplete and regularized Gamma functions with respect to the parameter x. I.e., Igamma.inv(a,y) returns the point x at which the (lower or upper) incomplete Gamma function with parameter a evaluates to y, and mutatis mutandis for Rgamma.inv(a,y). If log=TRUE, the parameter y is taken to be on a logarithmic scale as specified by base.

Cbeta returns the (complete) Beta function with arguments a and b, B(a,b). Ibeta returns the (lower or upper) incomplete Beta function with parameters a and b, evaluated at point x, B(x;a,b) (lower=TRUE) and B^*(x;a,b) (lower=FALSE). Note that in contrast to the Gamma functions, capital B refers to the lower incomplete Beta function, and there is no standardized notation for the upper incomplete Beta function, so B^* is used here as an ad-hoc symbol. Rbeta returns the corresponding regularized Beta function, I(x;a,b) (lower=TRUE) or I^*(x;a,b) (lower=FALSE). If log=TRUE, the returned values are on logarithmic scale as specified by the base parameter.

Ibeta.inv and Rbeta.inv compute the inverse of the incomplete and regularized Beta functions with respect to the parameter x. I.e., Ibeta.inv(y,a,b) returns the point x at which the (lower or upper) incomplete Beta function with parameters a and b evaluates to y, and mutatis mutandis for Rbeta.inv(y,a,b). If log=TRUE, the parameter y is taken to be on a logarithmic scale as specified by base.

All Gamma and Beta functions can be vectorized in the arguments x, y, a and b, with the usual R value recycling rules in the case of multiple vectorizations.

Mathematical Details

The upper incomplete Gamma function is defined by the Gamma integral

\Gamma(a,x) = \int_x^{\infty} t^{a-1} e^{-t}\,dt

The lower incomplete Gamma function is defined by the complementary Gamma integral

\gamma(a,x) = \int_0^x t^{a-1} e^{-t}\,dt

The complete Gamma function calculates the full Gamma integral, i.e. \Gamma(a) = \gamma(a,0). The regularized Gamma functions scale the corresponding incomplete Gamma functions to the interval [0,1], by dividing through \Gamma(a). Thus, the lower regularized Gamma function is given by

P(a,x) = \frac{\gamma(a,x)}{\Gamma(a)}

and the upper regularized Gamma function is given by

Q(a,x) = \frac{\Gamma(a,x)}{\Gamma(a)}

The lower incomplete Beta function is defined by the Beta integral

B(x;a,b) = \int_0^x t^{a-1} (1-t)^{b-1}\,dt

and the upper incomplete Beta function is defined by the complementary integral

B^*(x;a,b) = \int_x^1 t^{a-1} (1-t)^{b-1}\,dt

The complete Beta function calculates the full Beta integral, i.e. B(a,b) = B(1;a,b) = B^*(0;a,b). The regularized Beta function scales the incomplete Beta function to the interval [0,1], by dividing through B(a,b). The lower regularized Beta function is thus given by

I(x;a,b) = \frac{B(x;a,b)}{B(a,b)}

and the upper regularized Beta function is given by

I^*(x;a,b) = \frac{B^*(x;a,b)}{B(a,b)}

See Also

gamma and lgamma, which are fully equivalent to Cgamma. beta and lbeta, which are fully equivalent to Cbeta

The implementations of the incomplete and regularized Gamma functions are based on the Gamma distribution (see pgamma), and those of the Beta functions are based on the Beta distribution (see pbeta).

Examples

Cgamma(5 + 1) # = factorial(5)

## P(X >= k) for Poisson distribution with mean alpha
alpha <- 5
k <- 10
Rgamma(k, alpha) # == ppois(k-1, alpha, lower=FALSE)

n <- 49
k <- 6
1 / ((n+1) * Cbeta(n-k+1, k+1)) # == choose(n, k)

## P(X >= k) for binomial distribution with parameters n and p
n <- 100
p <- .1
k <- 15
Rbeta(p, k, n-k+1) # == pbinom(k-1, n, p, lower=FALSE)