\HeaderA{kappa}{Estimate the Condition Number}{kappa}
\methaliasA{kappa.default}{kappa}{kappa.default}
\methaliasA{kappa.lm}{kappa}{kappa.lm}
\methaliasA{kappa.qr}{kappa}{kappa.qr}
\methaliasA{kappa.tri}{kappa}{kappa.tri}
\keyword{math}{kappa}
\begin{Description}\relax
An estimate of the condition number of a matrix or of the \eqn{R}{} matrix of a
\eqn{QR}{} decomposition, perhaps of a linear fit.  The condition number is
defined as the ratio of the largest to the smallest \emph{non-zero}
singular value of the matrix.
\end{Description}
\begin{Usage}
\begin{verbatim}
kappa(z, ...)
## S3 method for class 'lm':
kappa(z, ...)
## Default S3 method:
kappa(z, exact = FALSE, ...)
## S3 method for class 'qr':
kappa(z, ...) 

kappa.tri(z, exact = FALSE, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{z}] A matrix or a the result of \code{\LinkA{qr}{qr}} or a fit from a class
inheriting from \code{"lm"}.
\item[\code{exact}] logical. Should the result be exact?
\item[\code{...}] further arguments passed to or from other methods.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
If \code{exact = FALSE} (the default) the condition number is estimated
by a cheap approximation. Following S, this uses the LINPACK routine
\file{dtrco.f}.  However, in \R{} (or S) the exact calculation is also
likely to be quick enough.

\code{kappa.tri} is an internal function called by \code{kappa.qr}.
\end{Details}
\begin{Value}
The condition number, \eqn{kappa}{}, or an approximation if
\code{exact = FALSE}.
\end{Value}
\begin{Author}\relax
The design was inspired by (but differs considerably from)
the S function of the same name described in Chambers (1992).
\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.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{svd}{svd}} for the singular value decomposition and
\code{\LinkA{qr}{qr}} for the \eqn{QR}{} one.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
kappa(x1 <- cbind(1,1:10))# 15.71
kappa(x1, exact = TRUE)        # 13.68
kappa(x2 <- cbind(x1,2:11))# high! [x2 is singular!]

hilbert <- function(n) { i <- 1:n; 1 / outer(i - 1, i, "+") }
sv9 <- svd(h9 <- hilbert(9))$ d
kappa(h9)# pretty high!
kappa(h9, exact = TRUE) == max(sv9) / min(sv9)
kappa(h9, exact = TRUE) / kappa(h9) # .677 (i.e., rel.error = 32%)
\end{ExampleCode}
\end{Examples}

