\HeaderA{qr}{The QR Decomposition of a Matrix}{qr}
\aliasA{as.qr}{qr}{as.qr}
\aliasA{is.qr}{qr}{is.qr}
\methaliasA{qr.coef}{qr}{qr.coef}
\methaliasA{qr.default}{qr}{qr.default}
\methaliasA{qr.fitted}{qr}{qr.fitted}
\methaliasA{qr.qty}{qr}{qr.qty}
\methaliasA{qr.qy}{qr}{qr.qy}
\methaliasA{qr.resid}{qr}{qr.resid}
\methaliasA{qr.solve}{qr}{qr.solve}
\aliasA{solve.qr}{qr}{solve.qr}
\keyword{algebra}{qr}
\keyword{array}{qr}
\begin{Description}\relax
\code{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.
\end{Description}
\begin{Usage}
\begin{verbatim}
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)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] a matrix whose QR decomposition is to be computed.
\item[\code{tol}] the tolerance for detecting linear dependencies in the
columns of \code{x}. Only used if \code{LAPACK} is false and
\code{x} is real.
\item[\code{qr}] a QR decomposition of the type computed by \code{qr}.
\item[\code{y, b}] a vector or matrix of right-hand sides of equations.
\item[\code{a}] A QR decomposition or (\code{qr.solve} only) a rectangular matrix.
\item[\code{k}] effective rank.
\item[\code{LAPACK}] logical. For real \code{x}, if true use LAPACK
otherwise use LINPACK.
\item[\code{...}] further arguments passed to or from other methods
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The QR decomposition plays an important role in many
statistical techniques.  In particular it can be used to solve the
equation \eqn{\bold{Ax} = \bold{b}}{} for given matrix \eqn{\bold{A}}{},
and vector \eqn{\bold{b}}{}.  It is useful for computing regression
coefficients and in applying the Newton-Raphson algorithm.

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

All the above functions keep \code{dimnames} (and \code{names}) of
\code{x} and \code{y} if there are.

\code{solve.qr} is the method for \code{\LinkA{solve}{solve}} for \code{qr} objects.
\code{qr.solve} solves systems of equations via the QR decomposition:
if \code{a} is a QR decomposition it is the same as \code{solve.qr},
but if \code{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.

\code{is.qr} returns \code{TRUE} if \code{x} is a \code{\LinkA{list}{list}}
with components named \code{qr}, \code{rank} and \code{qraux} and
\code{FALSE} otherwise.

It is not possible to coerce objects to mode \code{"qr"}.  Objects
either are QR decompositions or they are not.
\end{Details}
\begin{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.
\begin{ldescription}
\item[\code{qr}] a matrix with the same dimensions as \code{x}.
The upper triangle contains the \eqn{\bold{R}}{} of the decomposition
and the lower triangle contains information on the \eqn{\bold{Q}}{} of
the decomposition (stored in compact form).  Note that the storage
used by DQRDC and DGEQP3 differs.
\item[\code{qraux}] a vector of length \code{ncol(x)} which contains
additional information on \eqn{\bold{Q}}{}.
\item[\code{rank}] the rank of \code{x} as computed by the decomposition:
always full rank in the LAPACK case.
\item[\code{pivot}] information on the pivoting strategy used during
the decomposition.
\end{ldescription}


Non-complex QR objects computed by LAPACK have the attribute
\code{"useLAPACK"} with value \code{TRUE}.
\end{Value}
\begin{Note}\relax
To compute the determinant of a matrix (do you \emph{really} need it?),
the QR decomposition is much more efficient than using Eigen values
(\code{\LinkA{eigen}{eigen}}).  See \code{\LinkA{det}{det}}.

Using LAPACK (including in the complex case) uses column pivoting and
does not attempt to detect rank-deficient matrices.
\end{Note}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.

Dongarra, J. J., Bunch, J. R., Moler, C. B. and Stewart, G. W. (1978)
\emph{LINPACK Users Guide.}  Philadelphia: SIAM Publications.

Anderson. E. and ten others (1999)
\emph{LAPACK Users' Guide}. Third Edition. SIAM.\\
Available on-line at
\url{http://www.netlib.org/lapack/lug/lapack_lug.html}.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{qr.Q}{qr.Q}},  \code{\LinkA{qr.R}{qr.R}},  \code{\LinkA{qr.X}{qr.X}} for
reconstruction of the matrices.
\code{\LinkA{lm.fit}{lm.fit}},  \code{\LinkA{lsfit}{lsfit}},
\code{\LinkA{eigen}{eigen}}, \code{\LinkA{svd}{svd}}.

\code{\LinkA{det}{det}} (using \code{qr}) to compute the determinant of a matrix.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
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
\end{ExampleCode}
\end{Examples}

