\Header{Special}{Special Functions of Mathematics}
\alias{beta}{Special}
\alias{choose}{Special}
\alias{digamma}{Special}
\alias{factorial}{Special}
\alias{gamma}{Special}
\alias{lbeta}{Special}
\alias{lchoose}{Special}
\alias{lfactorial}{Special}
\alias{lgamma}{Special}
\alias{psigamma}{Special}
\alias{trigamma}{Special}
\keyword{math}{Special}
\begin{Description}\relax
Special mathematical functions related to the beta and gamma
functions.
\end{Description}
\begin{Usage}
\begin{verbatim}
beta(a, b)
lbeta(a, b)
gamma(x)
lgamma(x)
psigamma(x, deriv = 0)
digamma(x)
trigamma(x)
choose(n, k)
lchoose(n, k)
factorial(x)
lfactorial(x)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{a, b, x}] numeric vectors.
\item[\code{n, k, deriv}] integer vectors.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The functions \code{beta} and \code{lbeta} return the beta function
and the natural logarithm of the beta function,
\deqn{B(a,b) = \frac{\Gamma(a)\Gamma(b)}{\Gamma(a+b)}.}{B(a,b) = (Gamma(a)Gamma(b))/(Gamma(a+b)).}
The formal definition is
\deqn{B(a, b) = \int_0^1 t^{a-1} (1-t)^{b-1} dt}{integral_0^1 t^(a-1) (1-t)^(b-1) dt}
(Abramowitz and Stegun (6.2.1), page 258).

The functions \code{gamma} and \code{lgamma} return the gamma function
\eqn{\Gamma(x)}{} and the natural logarithm of the absolute value of the
gamma function.  The gamma function is defined by (Abramowitz and Stegun (6.1.1), page 255)
\deqn{\Gamma(x) = \int_0^\infty t^{a-1} e^{-t} dt}{integral_0^Inf t^(a-1) exp(-t) dt}
\code{factorial(x)} is \eqn{x!}{} and identical to
\code{gamma(x+1)} and \code{lfactorial} is \code{lgamma(x+1)}.

The functions \code{digamma} and \code{trigamma} return the first and second
derivatives of the logarithm of the gamma function.
\code{psigamma(x, deriv)} (\code{deriv >= 0}) is more generally
computing the \code{deriv}-th derivative of \eqn{\psi(x)}{}.
\deqn{\code{digamma(x)} = \psi(x) = \frac{d}{dx}\ln\Gamma(x) =
\frac{\Gamma'(x)}{\Gamma(x)}}{\code{digamma(x)} = psi(x) = d/dx {ln Gamma(x)} = Gamma'(x) / Gamma(x)}

The functions \code{choose} and \code{lchoose} return binomial
coefficients and their logarithms.

All the \code{*gamma*} functions are generic: methods can be
defined for them individually or via the \code{\Link{Math}} group generic.
\end{Details}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole. (for \code{gamma} and \code{lgamma}.)

Abramowitz, M. and Stegun, I. A. (1972)
\emph{Handbook of Mathematical Functions.} New York: Dover.
Chapter 6: Gamma and Related Functions.
\end{References}
\begin{SeeAlso}\relax
\code{\Link{Arithmetic}} for simple, \code{\Link{sqrt}} for
miscellaneous mathematical functions and \code{\Link{Bessel}} for the
real Bessel functions.

For the incomplete gamma function see \code{\Link{pgamma}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
choose(5, 2)
for (n in 0:10) print(choose(n, k = 0:n))

factorial(100)
lfactorial(10000)

## gamma has 1st order poles at 0, -1, -2, ...
x <- sort(c(seq(-3,4, length=201), outer(0:-3, (-1:1)*1e-6, "+")))
plot(x, gamma(x), ylim=c(-20,20), col="red", type="l", lwd=2,
     main=expression(Gamma(x)))
abline(h=0, v=-3:0, lty=3, col="midnightblue")

x <- seq(.1, 4, length = 201); dx <- diff(x)[1]
par(mfrow = c(2, 3))
for (ch in c("", "l","di","tri","tetra","penta")) {
  is.deriv <- nchar(ch) >= 2
  nm <- paste(ch, "gamma", sep = "")
  if (is.deriv) {
    dy <- diff(y) / dx # finite difference
    der <- which(ch == c("di","tri","tetra","penta")) - 1
    nm2 <- paste("psigamma(*, deriv = ", der,")",sep='')
    nm  <- if(der >= 2) nm2 else paste(nm, nm2, sep = " ==\n")
    y <- psigamma(x, deriv=der)
  } else {
    y <- get(nm)(x)
  }
  plot(x, y, type = "l", main = nm, col = "red")
  abline(h = 0, col = "lightgray")
  if (is.deriv) lines(x[-1], dy, col = "blue", lty = 2)
}

\end{ExampleCode}
\end{Examples}

