lm                   package:base                   R Documentation

Fitting Linear Models

Description:

     `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 `aov' may provide a more convenient interface
     for these).

Usage:

     lm(formula, data, subset, weights, na.action,
        method = "qr", model = TRUE, x = FALSE, y = FALSE, qr = TRUE,
        singular.ok = TRUE, contrasts = NULL, offset = NULL, ...)

Arguments:

 formula: a symbolic description of the model to be fit. The details of
          model specification are given below.

    data: an optional data frame containing the variables in the model.
           By default the variables are taken from
          `environment(formula)', typically the environment from which
          `lm' is called.

  subset: an optional vector specifying a subset of observations to be
          used in the fitting process.

 weights: an optional vector of weights to be used in the fitting
          process. If specified, weighted least squares is used with
          weights `weights' (that is, minimizing `sum(w*e^2)');
          otherwise ordinary least squares is used.

na.action: a function which indicates what should happen when the data
          contain `NA's.  The default is set by the `na.action' setting
          of `options', and is `na.fail' if that is unset. The
          ``factory-fresh'' default is `na.omit'.

  method: the method to be used; for fitting, currently only
          `method="qr"' is supported; `method="model.frame"' returns
          the model frame (the same as with `model = TRUE', see below).

model, x, y, qr: logicals.  If `TRUE' the corresponding components of
          the fit (the model frame, the model matrix, the response, the
          QR decomposition) are returned.

singular.ok: logical, defaulting to `TRUE'. `FALSE' is not yet
          implemented.

contrasts: an optional list. See the `contrasts.arg' of
          `model.matrix.default'.

  offset: this can be used to specify an a priori known component to be
          included in the linear predictor during fitting.  An `offset'
          term can be included in the formula instead or as well, and
          if both are specified their sum is used.

     ...: additional arguments to be passed to the low level regression
          fitting functions (see below).

Details:

     Models for `lm' are specified symbolically.  A typical model has
     the form `response ~ terms' where `response' is the (numeric)
     response vector and `terms' is a series of terms which specifies a
     linear predictor for `response'.  A terms specification of the
     form `first + second' indicates all the terms in `first' together
     with all the terms in `second' with duplicates removed.  A
     specification of the form `first:second' indicates the set of
     terms obtained by taking the interactions of all terms in `first'
     with all terms in `second'.  The specification `first*second'
     indicates the cross of `first' and `second'.  This is the same as
     `first + second + first:second'.

     `lm' calls the lower level functions `lm.fit', etc, see below, for
     the actual numerical computations.  For programming only, you may
     consider doing likewise.

Value:

     `lm' returns an object of `class' `"lm"' or for multiple responses
     of class `c("mlm", "lm")'.

     The functions `summary' and `anova' are used to obtain and print a
     summary and analysis of variance table of the results.  The
     generic accessor functions `coefficients', `effects',
     `fitted.values' and `residuals' extract various useful features of
     the value returned by `lm'.

     An object of class `"lm"' is a list containing at least the
     following components:

coefficients: a named vector of coefficients

residuals: the residuals, that is response minus fitted values.

fitted.values: the fitted mean values.

    rank: the numeric rank of the fitted linear model.

 weights: (only for weighted fits) the specified weights.

df.residual: the residual degrees of freedom.

    call: the matched call.

   terms: the `terms' object used.

contrasts: (only where relevant) the contrasts used.

 xlevels: (only where relevant) a record of the levels of the factors
          used in fitting.

       y: if requested, the response used.

       x: if requested, the model matrix used.

   model: if requested (the default), the model frame used.


     In addition, non-null fits will have components `assign',
     `effects' and (unless not requested) `qr' relating to the linear
     fit, for use by extractor functions such as `summary' and
     `effects'.

Note:

     Offsets specified by `offset' will not be included in predictions
     by `predict.lm', whereas those specified by an offset term in the
     formula will be.

See Also:

     `summary.lm' for summaries and `anova.lm' for the ANOVA table;
     `aov' for a different interface.

     The generic functions `coefficients', `effects', `residuals',
     `fitted.values'.

     `predict.lm' (via `predict') for prediction, including confidence
     and prediction intervals.

     `lm.influence' for regression diagnostics, and `glm' for
     generalized linear models.

     The underlying low level functions, `lm.fit' for plain, and
     `lm.wfit' for weighted regression fitting.

Examples:

     ## 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)))

