R: Bare-bones linear model fitting function

fastLm {RcppEigen} | R Documentation

## Bare-bones linear model fitting function

### Description

`fastLm` estimates the linear model using one of several methods implemented using the `Eigen` linear algebra library.

### Usage

    fastLmPure(X, y, method = 0L)
    fastLm(X, ...)
    ## Default S3 method:
    fastLm(X, y, method = 0L, ...)
    ## S3 method for class 'formula'
    fastLm(formula, data = list(), method = 0L, ...)

### Arguments

`y` | the response vector
`X` | a model matrix
`formula` | an object of class `"formula"` (or one that can be coerced to that class): a symbolic description of the model to be fitted. The details of model specification are given in the ‘Details’ section of the documentation for `lm`.
`data` | an optional data frame, list or environment (or object coercible by `as.data.frame` to a data frame) containing the variables in the model. If not found in `data`, the variables are taken from `environment(formula)`, typically the environment from which `lm` is called.
`method` | an integer scalar with value 0 for the column-pivoted QR decomposition, 1 for the unpivoted QR decomposition, 2 for the LLT Cholesky, 3 for the LDLT Cholesky, 4 for the Jacobi singular value decomposition (SVD) and 5 for a method based on the eigenvalue-eigenvector decomposition of X'X. Default is zero.
`...` | not used

### Details

Linear models should be estimated using the `lm` function. In some cases, `lm.fit` may be appropriate.

The `fastLmPure` function provides a reference use case of the `Eigen` C++ template library via the wrapper functions in the RcppEigen package.

The `fastLm` function provides a more standard implementation of a linear model fit, offering both a default and a formula interface as well as `print`, `summary` and `predict` methods.

Internally the `fastLm` function, by default, uses a QR decomposition with column pivots, which is a rank-revealing decomposition, so that it can handle rank-deficient cases effectively. Other methods for determining least squares solutions are available according to the value of the `method` argument.

An example of the type of situation requiring extra care in checking for rank deficiency is a two-way layout with missing cells (see the examples section). These cases require a special pivoting scheme of “pivot only on (apparent) rank deficiency” which is not part of conventional linear algebra software.

### Value

`fastLmPure` returns a list with several components:

`coefficients` | a vector of coefficients
`se` | a vector of the standard errors of the coefficient estimates
`rank` | a scalar denoting the computed rank of the model matrix
`df.residual` | a scalar denoting the degrees of freedom in the model
`residuals` | the vector of residuals
`s` | a numeric scalar - the root mean square for residuals
`fitted.values` | the vector of fitted value

`fastLm` returns a richer object which also includes the call argument similar to the `lm` or `rlm` functions..

### Author(s)

Eigen is described at http://eigen.tuxfamily.org. RcppEigen is written by Douglas Bates, Dirk Eddelbuettel and Romain Francois.

### References

Douglas Bates and Dirk Eddelbuettel (2013). Fast and Elegant Numerical Linear Algebra Using the RcppEigen Package. Journal of Statistical Software, 52(5), 1-24. URL http://www.jstatsoft.org/v52/i05/.

### See Also

`lm`, `lm.fit`

### Examples

      data(trees, package="datasets")
      mm <- cbind(1, log(trees$Girth))   # model matrix
      y  <- log(trees$Volume)            # response

      ## bare-bones direct interface
      flm <- fastLmPure(mm, y)
      print(flm)

      ## standard R interface for formula or data returning object of class fastLm
      flmmod <- fastLm( log(Volume) ~ log(Girth), data=trees)
      summary(flmmod)

      ## case where non-rank-revealing methods break down
      dd <- data.frame(f1 = gl(4, 6, labels = LETTERS[1:4]),
                       f2 = gl(3, 2, labels = letters[1:3]))[-(7:8), ]
      xtabs(~ f2 + f1, dd)     # one missing cell
      mm <- model.matrix(~ f1 * f2, dd)
      kappa(mm)                # large, indicating rank deficiency
      set.seed(1)
      dd$y <- mm %*% seq_len(ncol(mm)) + rnorm(nrow(mm), sd = 0.1)
      summary(lm(y ~ f1 * f2, dd))     # detects rank deficiency
      try(summary(fastLm(y ~ f1 * f2, dd))) # also detects rank deficiency

[Package RcppEigen version 0.3.2.9.1 Index]