\HeaderA{Poisson}{The Poisson Distribution}{Poisson}
\aliasA{dpois}{Poisson}{dpois}
\aliasA{ppois}{Poisson}{ppois}
\aliasA{qpois}{Poisson}{qpois}
\aliasA{rpois}{Poisson}{rpois}
\keyword{distribution}{Poisson}
\begin{Description}\relax
Density, distribution function, quantile function and random
generation for the Poisson distribution with parameter \code{lambda}.
\end{Description}
\begin{Usage}
\begin{verbatim}
dpois(x, lambda, log = FALSE)
ppois(q, lambda, lower.tail = TRUE, log.p = FALSE)
qpois(p, lambda, lower.tail = TRUE, log.p = FALSE)
rpois(n, lambda)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] vector of (non-negative integer) quantiles.
\item[\code{q}] vector of quantiles.
\item[\code{p}] vector of probabilities.
\item[\code{n}] number of random values to return.
\item[\code{lambda}] vector of (non-negative) means.
\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]}{P[X <= x]}, otherwise, \eqn{P[X > x]}{P[X > x]}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The Poisson distribution has density
\deqn{p(x) = \frac{\lambda^x e^{-\lambda}}{x!}}{p(x) = lambda^x exp(-lambda)/x!}
for \eqn{x = 0, 1, 2, \ldots}{}.  The mean and variance are
\eqn{E(X) = Var(X) = \lambda}{}.

If an element of \code{x} is not integer, the result of \code{dpois}
is zero, with a warning.
\eqn{p(x)}{} is computed using Loader's algorithm, see the reference in
\code{\LinkA{dbinom}{dbinom}}.

The quantile is left continuous: \code{qgeom(q, prob)} is the largest
integer \eqn{x}{} such that \eqn{P(X \le x) < q}{}.

Setting \code{lower.tail = FALSE} allows to get much more precise
results when the default, \code{lower.tail = TRUE} would return 1, see
the example below.
\end{Details}
\begin{Value}
\code{dpois} gives the (log) density,
\code{ppois} gives the (log) distribution function,
\code{qpois} gives the quantile function, and
\code{rpois} generates random deviates.

Invalid \code{lambda} will result in return value \code{NaN}, with a warning.
\end{Value}
\begin{Source}\relax
\code{dpois} uses C code contributed by Catherine Loader
(see \code{\LinkA{dbinom}{dbinom}}).

\code{ppois} uses \code{pgamma}.

\code{qpois} uses the Cornish--Fisher Expansion to include a skewness
correction to a normal approximation, followed by a search.

\code{rpois} uses

Ahrens, J. H. and Dieter, U. (1982).
Computer generation of Poisson deviates from modified normal distributions.
\emph{ACM Transactions on Mathematical Software}, \bold{8}, 163--179.
\end{Source}
\begin{SeeAlso}\relax
\code{\LinkA{dbinom}{dbinom}} for the binomial and \code{\LinkA{dnbinom}{dnbinom}} for
the negative binomial distribution.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
require(graphics)

-log(dpois(0:7, lambda=1) * gamma(1+ 0:7)) # == 1
Ni <- rpois(50, lambda = 4); table(factor(Ni, 0:max(Ni)))

1 - ppois(10*(15:25), lambda=100)  # becomes 0 (cancellation)
    ppois(10*(15:25), lambda=100, lower.tail=FALSE)     # no cancellation

par(mfrow = c(2, 1))
x <- seq(-0.01, 5, 0.01)
plot(x, ppois(x, 1), type="s", ylab="F(x)", main="Poisson(1) CDF")
plot(x, pbinom(x, 100, 0.01),type="s", ylab="F(x)",
     main="Binomial(100, 0.01) CDF")
\end{ExampleCode}
\end{Examples}

