\HeaderA{lm}{Fitting Linear Models}{lm}
\aliasA{print.lm}{lm}{print.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{\LinkA{aov}{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, ...)
\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, list or environment (or object
coercible by \code{\LinkA{as.data.frame}{as.data.frame}} to a data frame) containing
the variables in the model.  If not found in \code{data}, the
variables are taken from \code{environment(formula)},
typically the environment from which \code{lm} is called.
\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.  Should be \code{NULL} or a numeric vector.
If non-NULL, weighted least squares is used with weights
\code{weights} (that is, minimizing \code{sum(w*e\textasciicircum{}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{\LinkA{options}{options}}, and is
\code{\LinkA{na.fail}{na.fail}} if that is unset.  The \dQuote{factory-fresh}
default is \code{\LinkA{na.omit}{na.omit}}.  Another possible value is
\code{NULL}, no action.  Value \code{\LinkA{na.exclude}{na.exclude}} can be useful.
\item[\code{method}] the method to be used; for fitting, currently only
\code{method = "qr"} is supported; \code{method = "model.frame"} returns
the model frame (the same as with \code{model = TRUE}, see below).
\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. If \code{FALSE} (the default in S but
not in \R) a singular fit is an error.
\item[\code{contrasts}] an optional list. See the \code{contrasts.arg}
of \code{\LinkA{model.matrix.default}{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.  This should be \code{NULL} or a numeric vector of
length either one or equal to the number of cases.
One or more \code{\LinkA{offset}{offset}} terms can be included in the
formula instead or as well, and if both are specified their sum is
used.  See \code{\LinkA{model.offset}{model.offset}}.
\item[\code{...}] additional arguments to be passed to the low level
regression fitting functions (see below).
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Models for \code{lm} are specified symbolically.  A typical model has
the form \code{response \textasciitilde{} 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 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}.

If the formula includes an \code{\LinkA{offset}{offset}}, this is evaluated and
subtracted from the response.

If \code{response} is a matrix a linear model is fitted separately by
least-squares to each column of the matrix.

See \code{\LinkA{model.matrix}{model.matrix}} for some further details.  The terms in
the formula will be re-ordered so that main effects come first,
followed by the interactions, all second-order, all third-order and so
on: to avoid this pass a \code{terms} object as the formula (see
\code{\LinkA{aov}{aov}} and \code{demo(glm.vr)} for an example).

A formula has an implied intercept term.  To remove this use either
\code{y \textasciitilde{} x - 1} or \code{y \textasciitilde{} 0 + x}.  See \code{\LinkA{formula}{formula}} for
more details of allowed formulae.

\code{lm} calls the lower level functions \code{\LinkA{lm.fit}{lm.fit}}, etc,
see below, for the actual numerical computations.  For programming
only, you may consider doing likewise.

All of \code{weights}, \code{subset} and \code{offset} are evaluated
in the same way as variables in \code{formula}, that is first in
\code{data} and then in the environment of \code{formula}.
\end{Details}
\begin{Value}
\code{lm} returns an object of \code{\LinkA{class}{class}} \code{"lm"} or for
multiple responses of class \code{c("mlm", "lm")}.

The functions \code{summary} and \code{\LinkA{anova}{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}.

An object of class \code{"lm"} is a list containing at least the
following components:

\begin{ldescription}
\item[\code{coefficients}] a named vector of coefficients
\item[\code{residuals}] the residuals, that is response minus fitted values.
\item[\code{fitted.values}] the fitted mean values.
\item[\code{rank}] the numeric rank of the fitted linear model.
\item[\code{weights}] (only for weighted fits) the specified weights.
\item[\code{df.residual}] the residual degrees of freedom.
\item[\code{call}] the matched call.
\item[\code{terms}] the \code{\LinkA{terms}{terms}} object used.
\item[\code{contrasts}] (only where relevant) the contrasts used.
\item[\code{xlevels}] (only where relevant) a record of the levels of the
factors used in fitting.
\item[\code{offset}] the offset used (missing if none were used).
\item[\code{y}] if requested, the response used.
\item[\code{x}] if requested, the model matrix used.
\item[\code{model}] if requested (the default), the model frame used.
\end{ldescription}


In addition, non-null fits will have components \code{assign},
\code{effects} and (unless not requested) \code{qr} relating to the linear
fit, for use by extractor functions such as \code{summary} and
\code{\LinkA{effects}{effects}}.
\end{Value}
\begin{Section}{Using time series}
Considerable care is needed when using \code{lm} with time series.

Unless \code{na.action = NULL}, the time series attributes are
stripped from the variables before the regression is done.  (This is
necessary as omitting \code{NA}s would invalidate the time series
attributes, and if \code{NA}s are omitted in the middle of the series
the result would no longer be a regular time series.)

Even if the time series attributes are retained, they are not used to
line up series, so that the time shift of a lagged or differenced
regressor would be ignored.  It is good practice to prepare a
\code{data} argument by \code{\LinkA{ts.intersect}{ts.intersect}(..., dframe = TRUE)},
then apply a suitable \code{na.action} to that data frame and call
\code{lm} with \code{na.action = NULL} so that residuals and fitted
values are time series.
\end{Section}
\begin{Note}\relax
Offsets specified by \code{offset} will not be included in predictions
by \code{\LinkA{predict.lm}{predict.lm}}, whereas those specified by an offset term
in the formula will be.
\end{Note}
\begin{Author}\relax
The design was inspired by the S function of the same name described
in Chambers (1992).  The implementation of model formula by Ross Ihaka
was based on Wilkinson \& Rogers (1973).
\end{Author}
\begin{References}\relax
Chambers, J. M. (1992)
\emph{Linear models.}
Chapter 4 of \emph{Statistical Models in S}
eds J. M. Chambers and T. J. Hastie, Wadsworth \& Brooks/Cole.

Wilkinson, G. N. and Rogers, C. E. (1973)
Symbolic descriptions of factorial models for analysis of variance.
\emph{Applied Statistics}, \bold{22}, 392--9.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{summary.lm}{summary.lm}} for summaries and \code{\LinkA{anova.lm}{anova.lm}} for
the ANOVA table; \code{\LinkA{aov}{aov}} for a different interface.

The generic functions \code{\LinkA{coef}{coef}}, \code{\LinkA{effects}{effects}},
\code{\LinkA{residuals}{residuals}}, \code{\LinkA{fitted}{fitted}}, \code{\LinkA{vcov}{vcov}}.

\code{\LinkA{predict.lm}{predict.lm}} (via \code{\LinkA{predict}{predict}}) for prediction,
including confidence and prediction intervals;
\code{\LinkA{confint}{confint}} for confidence intervals of \emph{parameters}.

\code{\LinkA{lm.influence}{lm.influence}} for regression diagnostics, and
\code{\LinkA{glm}{glm}} for \bold{generalized} linear models.

The underlying low level functions,
\code{\LinkA{lm.fit}{lm.fit}} for plain, and \code{\LinkA{lm.wfit}{lm.wfit}} for weighted
regression fitting.
\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)

## model frame :
stopifnot(identical(lm(weight ~ group, method = "model.frame"),
                    model.frame(lm.D9)))
\end{ExampleCode}
\end{Examples}

