\Header{loess}{Local Polynomial Regression Fitting}
\keyword{smooth}{loess}
\begin{Usage}
\begin{verbatim}
loess(formula, data, weights, subset, na.action, model=FALSE,
      span=0.75, enp.target, degree=2,
      parametric=FALSE, drop.square=FALSE, normalize=TRUE,
      family=c("gaussian", "symmetric"),
      method=c("loess", "model.frame"),
      control=loess.control(...), ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\texttt{formula}] a formula specifying the response and one or more
numeric predictors (best specified via an interaction, but can also
be specified additively).
\item[\texttt{data}] an optional data frame within which to look first for the
response, predictors and weights,
\item[\texttt{weights}] optional weights for each case.
\item[\texttt{subset}] an optional specification of a subset of the data to be used.
\item[\texttt{na.action}] the action to be taken with missing values in the
response or predictors. The default is to stop.
\item[\texttt{model}] should the model frame be returned?
\item[\texttt{span}] the parameter \eqn{\alpha}{} which controls the degree of
smoothing.
\item[\texttt{enp.target}] an alternative way to specify \texttt{span}, as the
approximate equivalent number of parameters to be used.
\item[\texttt{degree}] the degree of the polynomials to be used, up to 2.
\item[\texttt{parametric}] should any terms be fitted globally rather than
locally? Terms can be specified by name, number or as a logical
vector of the same length as the number of predictors.
\item[\texttt{drop.square}] for fits with more than one predictor and
\texttt{degree=2}, should the quadratic term (and cross-terms) be
dropped for particular predictors? Terms are specified in the same way
as for \texttt{parametric}.
\item[\texttt{normalize}] should the predictors be normalized to a common scale
if there is more than one? The normalization used is to set the
10\% trimmed standard deviation to one. Set to false for spatial
coordinate predictors and others know to be a common scale.
\item[\texttt{family}] if \texttt{family="gaussian"} fitting is by least-squares,
and if \texttt{family="symmetric"} a re-descending M estimator is used
with Tukey's biweight function.
\item[\texttt{method}] fit the model or just extract the model frame.
\item[\texttt{control}] control parameters: see \texttt{\Link{loess.control}}.
\item[\texttt{...}] control parameters can also be supplied directly.
\end{ldescription}
\end{Arguments}
\begin{Description}
Fit a polynomial surface determined by one or more numerical
predictors, using local fitting.\end{Description}
\begin{Details}
Fitting is done locally.  That is, for the fit at point x, the fit is
made using points in a neighbourhood of x, weighted by their distance
from x (with differences in `parametric' variables being ignored when
computing the distance). The size of the neighbourhood is controlled
by \eqn{\alpha}{} (set by \texttt{span} or \texttt{enp.target}).  For
\eqn{\alpha < 1}{}, the neighbourhood includes proportion \eqn{\alpha}{}
of the points, and these have tricubic weighting (proportional to
\eqn{(1 - \mathrm{(dist/maxdist)}^3)^3}{(1 - (dist/maxdist)^3)^3}.
For \eqn{\alpha > 1}{}, all points are used, with the `maximum distance'
assumed to be \eqn{\alpha}{} times the actual maximum distance.

For the default family, fitting is by (weighted) least squares. For
\texttt{family="symmetric"} a few iterations of an M-estimation
procedure with Tukey' biweight are used. Be aware that as the initial
value is the least-squares fit, this need not be a very resistant fit.

It can be important to tune the control list to achieve acceptable
speed. See \link{loess.control} for details.\end{Details}
\begin{Value}
An object of class \texttt{"loess"}.\end{Value}
\begin{Note}
As this is based on the \texttt{cloess} package available at
\texttt{netlib}, it is similar to but not identical to the \texttt{loess}
function of S. In particular, conditioning is not implemented.

The memory usage of this implementation of \texttt{loess} is roughly
quadratic in the number of points, with 1000 points taking about 10Mb.\end{Note}
\begin{Author}
B.D. Ripley, based on the \texttt{cloess} package of Cleveland,
Grosse and Shyu.\end{Author}
\begin{References}
W.S. Cleveland, E. Grosse and W.M. Shyu (1992) Local regression
models. Chapter 8 of \emph{Statistical Models in S} eds J.M. Chambers
and T.J. Hastie, Wadsworth \& Brooks/Cole.\end{References}
\begin{SeeAlso}
\texttt{\Link{loess.control}}, \texttt{\Link{predict.loess}}\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
data(cars)
cars.lo <- loess(dist ~ speed, cars)
predict(cars.lo, data.frame(speed=seq(5, 30, 1)), se=TRUE)
# to get extrapolation
cars.lo2 <- loess(dist ~ speed, cars,
  control=loess.control(surface="direct"))
predict(cars.lo2, data.frame(speed=seq(5, 30, 1)), se=TRUE)
\end{ExampleCode}
\end{Examples}

