\Header{density}{Kernel Density Estimation}
\alias{print.density}{density}
\alias{plot.density}{density}
\keyword{dplot}{density}
\keyword{distribution}{density}
\keyword{smooth}{density}
\begin{Usage}
\begin{verbatim}
density(x, bw, adjust = 1, kernel="gaussian", window = kernel,
        n = 512, width, from, to, cut = 3, na.rm = FALSE)
print(dobj)
plot(dobj, main = NULL, xlab = NULL, ylab = "Density", type = "l",
     zero.line = TRUE, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\texttt{x}] the data from which the estimate is to be computed.
\item[\texttt{n}] the number of equally spaced points at which the density
is to be estimated.  When \texttt{n > 512}, it is rounded up to the next
power of 2 for efficieny reasons (\texttt{\Link{fft}}).
\item[\texttt{kernel,window}] a character string giving the smoothing kernel to be used.
This must be one of \texttt{"gaussian"}, \texttt{"rectangular"},
\texttt{"triangular"}, or \texttt{"cosine"}, and may be abbreviated to a
single letter.
\item[\texttt{bw}] the smoothing bandwith to be used.  This is the standard
deviation of the smoothing kernel.  It defaults to 0.9 times the
minimum of the standard deviation and the interquartile range divided by
1.34 times the sample size to the negative one fifth power
(= Silverman's ``rule of thumb'').
The specified value of \texttt{bw} is multiplied by \texttt{adjust}.
\item[\texttt{adjust}] the bandwith used is actually \texttt{adjust*bw}.
This makes it easy to specify values like ``half the default'' bandwidth.
\item[\texttt{width}] this exists for compatibility with S.
\item[\texttt{from,to}] the left and right-most points of the grid at which the
density is to be estimated.
\item[\texttt{cut}] by default, the values of \texttt{left} and \texttt{right} are
\texttt{cut} bandwidths beyond the extremes of the data. This allows the
estimated density to drop to approximately zero at the extremes.
\item[\texttt{na.rm}] logical; if \texttt{TRUE}, missing values are eliminated from
\texttt{x} in advance to further computation.
\item[\texttt{dobj}] a ``density'' object.
\item[\texttt{main, xlab, ylab, type}] plotting parameters with useful defaults.
\item[\texttt{...}] further plotting parameters.
\item[\texttt{zero.line}] logical; if \texttt{TRUE}, add a base line at \eqn{y = 0}{}
\end{ldescription}
\end{Arguments}
\begin{Description}
The function \texttt{density} computes kernel density estimates
with the given kernel and bandwidth.

The generic functions \texttt{plot} and \texttt{print} have
methods for density objects.\end{Description}
\begin{Details}
The algorithm used in \texttt{density} disperses the mass of the
empirical distribution function over a regular grid of at least 512
points and then
uses the fast Fourier transform to convolve this approximation
with a discretized version of the kernel and then uses linear
approximation to evaluate the density at the specified points.\end{Details}
\begin{Value}
An object with class \texttt{"density"}.
The underlying structure is a list containing the following components.
\begin{ldescription}
\item[\texttt{x}] the \texttt{n} coordinates of the points where the density is estimated.
\item[\texttt{y}] the estimated density values.
\item[\texttt{bw}] the bandwidth used.
\item[\texttt{N}] the sample size \texttt{length(x)}.
\item[\texttt{call}] the call which produced the result.
\item[\texttt{data.name}] the deparsed name of the \texttt{x} argument.
\item[\texttt{has.na}] logical, indicating if there were \texttt{\Link{NA}}s in the
sample \emph{and} \texttt{na.rm == FALSE}.
\end{ldescription}
\end{Value}
\begin{References}
Silverman, B. W. (1986).
\emph{Density Estimation}.
London: Chapman and Hall.

Venables, W. N. and B. D. Ripley (1994).
\emph{Modern Applied Statistics with S-Plus}.
New York: Springer.

Scott, D. W. (1992).
\emph{Multivariate Density Estimation.  Theory, Practice and Visualization}.
New York: Wiley.

Sheather, S. J. and M. C. Jones (1991).
``A reliable data-based bandwidth selection method for kernel density
estimation.
\emph{J. Roy. Statist. Soc.} \bold{B}, 683-690.\end{References}
\begin{SeeAlso}
\texttt{\Link{convolve}}, \texttt{\Link{hist}}.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
# The Old Faithful geyser data
data(faithful)
d <- density(faithful$eruptions, bw=0.15)
d
plot(d)

plot(d, type="n")
polygon(d, col="wheat")

## Missing values:
x <- xx <- faithful$eruptions
x[i.out <- sample(length(x), 10)] <- NA
doR <- density(x, bw=0.15, na.rm = TRUE)
doN <- density(x, bw=0.15, na.rm = FALSE)
lines(doR, col="blue")
lines(doN, col="red")
points(xx[i.out], rep(.01,10))
\end{ExampleCode}
\end{Examples}

