\Header{lm}{Fitting Linear Models}
\methalias{lm.fit}{lm}
\alias{lm.fit.null}{lm}
\alias{lm.wfit}{lm}
\methalias{lm.wfit.null}{lm}
\keyword{regression}{lm}
\begin{Description}\relax
\code{lm} is used to fit linear models.
It can be used to carry out regression,
single stratum analysis of variance and
analysis of covariance (although \code{\Link{aov}} may provide a more
convenient interface for these).\end{Description}
\begin{Usage}
\begin{verbatim}
lm(formula, data, subset, weights, na.action,
   method = "qr", model = TRUE, x = FALSE, y = FALSE, qr = TRUE,
   singular.ok = TRUE contrasts = NULL, offset = NULL, ...)

lm.fit (x, y,    offset = NULL, method = "qr", tol = 1e-7, ...)
lm.wfit(x, y, w, offset = NULL, method = "qr", tol = 1e-7, ...)
lm.fit.null (x, y,    method = "qr", tol = 1e-7, ...)
lm.wfit.null(x, y, w, method = "qr", tol = 1e-7, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{formula}] a symbolic description of the model to be fit.
The details of model specification are given below.
\item[\code{data}] an optional data frame containing the variables
in the model.  By default the variables are taken from
the environment which \code{lm} is called from.
\item[\code{subset}] an optional vector specifying a subset of observations
to be used in the fitting process.
\item[\code{weights}] an optional vector of weights to be used
in the fitting process. If specified, weighted least squares is used
with weights \code{weights} (that is, minimizing \code{sum(w*e$\,\hat{\,}$2)});
otherwise ordinary least squares is used.
\item[\code{na.action}] a function which indicates what should happen
when the data contain \code{NA}s.  The default is set by
the \code{na.action} setting of \code{\Link{options}}, and is
\code{\Link{na.fail}} if that is unset. The ``factory-fresh''
default is \code{\Link{na.omit}}.
\item[\code{model, x, y, qr}] logicals.  If \code{TRUE} the corresponding
components of the fit (the model frame, the model matrix, the
response, the QR decomposition) are returned.
\item[\code{singular.ok}] logical, defaulting to
\code{TRUE}. \emph{\code{FALSE} is not yet implemented}.
\item[\code{method}] currently, only \code{method="qr"} is supported.
\item[\code{contrasts}] an optional list. See the \code{contrasts.arg}
of \code{model.matrix.default}.
\item[\code{offset}] this can be used to specify an \emph{a priori}
known component to be included in the linear predictor
during fitting.  An \code{\Link{offset}} term can be included in the
formula instead or as well, and if both are specified their sum is used.
\item[\code{tol}] tolerance for the \code{\Link{qr}} decomposition. Default
is 1e-7.
\item[\code{...}] currently disregarded.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Models for \code{lm} are specified symbolically.  A typical model has
the form \code{response $\,\tilde{\,}$ terms} where \code{response} is the (numeric)
response vector and \code{terms} is a series of terms which specifies a
linear predictor for \code{response}.  A terms specification of the form
\code{first+second} indicates all the terms in \code{first} together
with all the terms in \code{second} with duplicates removed.  A
specification of the form \code{first:second} indicates the the set of
terms obtained by taking the interactions of all terms in \code{first}
with all terms in \code{second}.  The specification \code{first*second}
indicates the \emph{cross} of \code{first} and \code{second}.  This is
the same as \code{first+second+first:second}.\end{Details}
\begin{Value}
\code{lm} returns an object of \code{\Link{class}} \code{"lm"} or for
multiple responses of class \code{c("mlm", "lm")}.

The functions \code{summary} and \code{\Link{anova}} are used to
obtain and print a summary and analysis of variance table of the results.
The generic accessor functions \code{coefficients},
\code{effects}, \code{fitted.values} and \code{residuals}
extract various useful features of the value returned by \code{lm}.\end{Value}
\begin{Note}\relax
Offsets specified by \code{offset} will not be included in predictions
by \code{\Link{predict.lm}}, whereas those specified by an offset term
in the formula will be.\end{Note}
\begin{SeeAlso}\relax
\code{\Link{summary.lm}} for summaries and \code{\Link{anova.lm}} for
the ANOVA table; \code{\Link{aov}} for a different interface.

The generic functions \code{\Link{coefficients}}, \code{\Link{effects}},
\code{\Link{residuals}}, \code{\Link{fitted.values}}.

\code{\Link{predict.lm}} (via \code{predict(..)}) for prediction,
including confidence and prediction intervals.

\code{\Link{lm.influence}} for regression diagnostics, and
\code{\Link{glm}} for \bold{generalized} linear models.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## Annette Dobson (1990) "An Introduction to Generalized Linear Models".
## Page 9: Plant Weight Data.
ctl <- c(4.17,5.58,5.18,6.11,4.50,4.61,5.17,4.53,5.33,5.14)
trt <- c(4.81,4.17,4.41,3.59,5.87,3.83,6.03,4.89,4.32,4.69)
group <- gl(2,10,20, labels=c("Ctl","Trt"))
weight <- c(ctl, trt)
anova(lm.D9 <- lm(weight ~ group))
summary(lm.D90 <- lm(weight ~ group - 1))# omitting intercept
summary(resid(lm.D9) - resid(lm.D90)) #- residuals almost identical

opar <- par(mfrow = c(2,2), oma = c(0, 0, 1.1, 0))
plot(lm.D9, las = 1)      # Residuals, Fitted, ...
par(opar)
\end{ExampleCode}
\end{Examples}

