\HeaderA{Hypergeometric}{The Hypergeometric Distribution}{Hypergeometric}
\aliasA{dhyper}{Hypergeometric}{dhyper}
\aliasA{phyper}{Hypergeometric}{phyper}
\aliasA{qhyper}{Hypergeometric}{qhyper}
\aliasA{rhyper}{Hypergeometric}{rhyper}
\keyword{distribution}{Hypergeometric}
\begin{Description}\relax
Density, distribution function, quantile function and random
generation for the hypergeometric distribution.
\end{Description}
\begin{Usage}
\begin{verbatim}
dhyper(x, m, n, k, log = FALSE)
phyper(q, m, n, k, lower.tail = TRUE, log.p = FALSE)
qhyper(p, m, n, k, lower.tail = TRUE, log.p = FALSE)
rhyper(nn, m, n, k)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x, q}] vector of quantiles representing the number of white balls
drawn without replacement from an urn which contains both black and
white balls.
\item[\code{m}] the number of white balls in the urn.
\item[\code{n}] the number of black balls in the urn.
\item[\code{k}] the number of balls drawn from the urn.
\item[\code{p}] probability, it must be between 0 and 1.
\item[\code{nn}] number of observations. If \code{length(nn) > 1}, the length
is taken to be the number required.
\item[\code{log, log.p}] logical; if TRUE, probabilities p are given as log(p).
\item[\code{lower.tail}] logical; if TRUE (default), probabilities are
\eqn{P[X \le x]}{}, otherwise, \eqn{P[X > x]}{}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The hypergeometric distribution is used for sampling \emph{without}
replacement.  The density of this distribution with parameters
\code{m}, \code{n} and \code{k} (named \eqn{Np}{}, \eqn{N-Np}{}, and
\eqn{n}{}, respectively in the reference below) is given by
\deqn{
p(x) = \left. {m \choose x}{n \choose k-x} \right/ {m+n \choose k}
}{}
for \eqn{x = 0, \ldots, k}{}.

The quantile is defined as the smallest value \eqn{x}{} such that
\eqn{F(x) \ge p}{}, where \eqn{F}{} is the distribution function.
\end{Details}
\begin{Value}
\code{dhyper} gives the density,
\code{phyper} gives the distribution function,
\code{qhyper} gives the quantile function, and
\code{rhyper} generates random deviates.

Invalid arguments will result in return value \code{NaN}, with a warning.
\end{Value}
\begin{Source}\relax
\code{dhyper} computes via binomial probabilities, using code
contributed by Catherine Loader (see \code{\LinkA{dbinom}{dbinom}}).

\code{phyper} is based on calculating \code{dhyper} and
\code{phyper(...)/dhyper(...)} (as a summation), based on ideas of Ian
Smith and Morten Welinder.

\code{qhyper} is based on inversion.

\code{rhyper} is based on a corrected version of

Kachitvichyanukul, V. and Schmeiser, B. (1985).
Computer generation of hypergeometric random variates.
\emph{Journal of Statistical Computation and Simulation},
\bold{22}, 127--145.
\end{Source}
\begin{References}\relax
Johnson, N. L., Kotz, S., and Kemp, A. W. (1992)
\emph{Univariate Discrete Distributions},
Second Edition. New York: Wiley.
\end{References}
\begin{Examples}
\begin{ExampleCode}
m <- 10; n <- 7; k <- 8
x <- 0:(k+1)
rbind(phyper(x, m, n, k), dhyper(x, m, n, k))
all(phyper(x, m, n, k) == cumsum(dhyper(x, m, n, k)))# FALSE
## but error is very small:
signif(phyper(x, m, n, k) - cumsum(dhyper(x, m, n, k)), digits=3)
\end{ExampleCode}
\end{Examples}

