| % File src/library/base/man/svd.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2017 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{svd} |
| \alias{svd} |
| \alias{La.svd} |
| \title{Singular Value Decomposition of a Matrix} |
| \description{ |
| Compute the singular-value decomposition of a rectangular matrix. |
| } |
| \usage{ |
| svd(x, nu = min(n, p), nv = min(n, p), LINPACK = FALSE) |
| |
| La.svd(x, nu = min(n, p), nv = min(n, p)) |
| } |
| \arguments{ |
| \item{x}{a numeric or complex matrix whose SVD decomposition |
| is to be computed. Logical matrices are coerced to numeric.} |
| \item{nu}{the number of left singular vectors to be computed. |
| This must between \code{0} and \code{n = nrow(x)}.} |
| \item{nv}{the number of right singular vectors to be computed. |
| This must be between \code{0} and \code{p = ncol(x)}.} |
| \item{LINPACK}{logical. Defunct and ignored.} |
| } |
| \details{ |
| The singular value decomposition plays an important role in many |
| statistical techniques. \code{svd} and \code{La.svd} provide two |
| interfaces which differ in their return values. |
| |
| Computing the singular vectors is the slow part for large matrices. |
| The computation will be more efficient if both \code{nu <= min(n, p)} |
| and \code{nv <= min(n, p)}, and even more so if both are zero. |
| |
| Unsuccessful results from the underlying LAPACK code will result in an |
| error giving a positive error code (most often \code{1}): these can |
| only be interpreted by detailed study of the FORTRAN code but mean |
| that the algorithm failed to converge. |
| } |
| \value{ |
| The SVD decomposition of the matrix as computed by LAPACK, \deqn{ |
| \bold{X = U D V'},} where \eqn{\bold{U}} and \eqn{\bold{V}} are |
| orthogonal, \eqn{\bold{V'}} means \emph{V transposed} (and conjugated |
| for complex input), and \eqn{\bold{D}} is a diagonal matrix with the |
| (non-negative) singular values \eqn{D_{ii}}{D[i,i]} in decreasing |
| order. Equivalently, \eqn{\bold{D = U' X V}}, which is verified in |
| the examples. |
| |
| The returned value is a list with components |
| \item{d}{a vector containing the singular values of \code{x}, of |
| length \code{min(n, p)}, sorted decreasingly.} |
| \item{u}{a matrix whose columns contain the left singular vectors of |
| \code{x}, present if \code{nu > 0}. Dimension \code{c(n, nu)}.} |
| \item{v}{a matrix whose columns contain the right singular vectors of |
| \code{x}, present if \code{nv > 0}. Dimension \code{c(p, nv)}.} |
| |
| Recall that the singular vectors are only defined up to sign (a |
| constant of modulus one in the complex case). If a left singular |
| vector has its sign changed, changing the sign of the corresponding |
| right vector gives an equivalent decomposition. |
| |
| For \code{La.svd} the return value replaces \code{v} by \code{vt}, the |
| (conjugated if complex) transpose of \code{v}. |
| } |
| \source{ |
| The main functions used are the LAPACK routines \code{DGESDD} and |
| \code{ZGESDD}. |
| |
| LAPACK is from \url{http://www.netlib.org/lapack} and its guide is |
| listed in the references. |
| } |
| \references{ |
| Anderson. E. and ten others (1999) |
| \emph{LAPACK Users' Guide}. Third Edition. SIAM.\cr |
| Available on-line at |
| \url{http://www.netlib.org/lapack/lug/lapack_lug.html}. |
| |
| The \href{https://en.wikipedia.org/wiki/Singular-value_decomposition}{% |
| \sQuote{Singular-value decomposition}} Wikipedia article. |
| |
| Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) |
| \emph{The New S Language}. |
| Wadsworth & Brooks/Cole. |
| } |
| |
| \seealso{ |
| \code{\link{eigen}}, \code{\link{qr}}. |
| } |
| \examples{ |
| hilbert <- function(n) { i <- 1:n; 1 / outer(i - 1, i, "+") } |
| X <- hilbert(9)[, 1:6] |
| (s <- svd(X)) |
| D <- diag(s$d) |
| s$u \%*\% D \%*\% t(s$v) # X = U D V' |
| t(s$u) \%*\% X \%*\% s$v # D = U' X V |
| } |
| \keyword{algebra} |
| \keyword{array} |
| |