qr                   package:base                   R Documentation

The QR Decomposition of a Matrix

Description:

     'qr' computes the QR decomposition of a matrix.  It provides an
     interface to the techniques used in the LINPACK routine DQRDC or
     the LAPACK routines DGEQP3 and (for complex matrices) ZGEQP3.

Usage:

     qr(x, ...)
     ## Default S3 method:
     qr(x, tol = 1e-07 , LAPACK = FALSE, ...)

     qr.coef(qr, y)
     qr.qy(qr, y)
     qr.qty(qr, y)
     qr.resid(qr, y)
     qr.fitted(qr, y, k = qr$rank)
     qr.solve(a, b, tol = 1e-7)
     ## S3 method for class 'qr':
     solve(a, b, ...)

     is.qr(x)
     as.qr(x)

Arguments:

       x: a matrix whose QR decomposition is to be computed.

     tol: the tolerance for detecting linear dependencies in the
          columns of 'x'. Only used if 'LAPACK' is false and 'x' is
          real.

      qr: a QR decomposition of the type computed by 'qr'.

    y, b: a vector or matrix of right-hand sides of equations.

       a: A QR decomposition or ('qr.solve' only) a rectangular matrix.

       k: effective rank.

  LAPACK: logical. For real 'x', if true use LAPACK otherwise use
          LINPACK.

     ...: further arguments passed to or from other methods

Details:

     The QR decomposition plays an important role in many statistical
     techniques.  In particular it can be used to solve the equation
     *Ax* = *b* for given matrix *A*, and vector *b*.  It is useful for
     computing regression coefficients and in applying the
     Newton-Raphson algorithm.

     The functions 'qr.coef', 'qr.resid', and 'qr.fitted' return the
     coefficients, residuals and fitted values obtained when fitting
     'y' to the matrix with QR decomposition 'qr'. (If pivoting is
     used, some of the coefficients will be 'NA'.) 'qr.qy' and 'qr.qty'
     return 'Q %*% y' and 't(Q) %*% y', where 'Q' is the (complete) *Q*
     matrix.

     All the above functions keep 'dimnames' (and 'names') of 'x' and
     'y' if there are.

     'solve.qr' is the method for 'solve' for 'qr' objects. 'qr.solve'
     solves systems of equations via the QR decomposition: if 'a' is a
     QR decomposition it is the same as 'solve.qr', but if 'a' is a
     rectangular matrix the QR decomposition is computed first.  Either
     will handle over- and under-determined systems, providing a
     least-squares fit if appropriate.

     'is.qr' returns 'TRUE' if 'x' is a 'list' with components named
     'qr', 'rank' and 'qraux' and 'FALSE' otherwise.

     It is not possible to coerce objects to mode '"qr"'.  Objects
     either are QR decompositions or they are not.

Value:

     The QR decomposition of the matrix as computed by LINPACK or
     LAPACK. The components in the returned value correspond directly
     to the values returned by DQRDC/DGEQP3/ZGEQP3. 

      qr: a matrix with the same dimensions as 'x'. The upper triangle
          contains the *R* of the decomposition and the lower triangle
          contains information on the *Q* of the decomposition (stored
          in compact form).  Note that the storage used by DQRDC and
          DGEQP3 differs.

   qraux: a vector of length 'ncol(x)' which contains additional
          information on *Q*.

    rank: the rank of 'x' as computed by the decomposition: always full
          rank in the LAPACK case.

   pivot: information on the pivoting strategy used during the
          decomposition.


     Non-complex QR objects computed by LAPACK have the attribute
     '"useLAPACK"' with value 'TRUE'.

Note:

     To compute the determinant of a matrix (do you _really_ need it?),
     the QR decomposition is much more efficient than using Eigen
     values ('eigen').  See 'det'.

     Using LAPACK (including in the complex case) uses column pivoting
     and does not attempt to detect rank-deficient matrices.

References:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

     Dongarra, J. J., Bunch, J. R., Moler, C. B. and Stewart, G. W.
     (1978) _LINPACK Users Guide._  Philadelphia: SIAM Publications.

     Anderson. E. and ten others (1999) _LAPACK Users' Guide_. Third
     Edition. SIAM.
      Available on-line at <URL:
     http://www.netlib.org/lapack/lug/lapack_lug.html>.

See Also:

     'qr.Q',  'qr.R',  'qr.X' for reconstruction of the matrices.
     'lm.fit',  'lsfit', 'eigen', 'svd'.

     'det' (using 'qr') to compute the determinant of a matrix.

Examples:

     hilbert <- function(n) { i <- 1:n; 1 / outer(i - 1, i, "+") }
     h9 <- hilbert(9); h9
     qr(h9)$rank           #--> only 7
     qrh9 <- qr(h9, tol = 1e-10)
     qrh9$rank             #--> 9
     ##-- Solve linear equation system  H %*% x = y :
     y <- 1:9/10
     x <- qr.solve(h9, y, tol = 1e-10) # or equivalently :
     x <- qr.coef(qrh9, y) #-- is == but much better than
                           #-- solve(h9) %*% y
     h9 %*% x              # = y

     ## overdetermined system
     A <- matrix(runif(12), 4)
     b <- 1:4
     qr.solve(A, b) # or solve(qr(A), b)
     solve(qr(A, LAPACK=TRUE), b)
     # this is a least-squares solution, cf. lm(b ~ 0 + A)

     ## underdetermined system
     A <- matrix(runif(12), 3)
     b <- 1:3
     qr.solve(A, b)
     solve(qr(A, LAPACK=TRUE), b)
     # solutions will have one zero, not necessarily the same one

