R: Find the Largest k Singular Values/Vectors of a Matrix

svds {RSpectra} | R Documentation

## Find the Largest k Singular Values/Vectors of a Matrix

### Description

Given an m by n matrix A, function `svds()` can find its largest k singular values and the corresponding singular vectors. It is also called the Truncated SVD or Partial SVD since it only calculates a subset of the whole singular triplets.

Currently `svds()` supports matrices of the following classes:

`matrix` | The most commonly used matrix type, defined in base package.
`dgeMatrix` | General matrix, equivalent to `matrix`, defined in Matrix package.
`dgCMatrix` | Column oriented sparse matrix, defined in Matrix package.
`dgRMatrix` | Row oriented sparse matrix, defined in Matrix package.
`dsyMatrix` | Symmetrix matrix, defined in Matrix package.
`function` | Implicitly specify the matrix through two functions that calculate f(x) = A * x and g(x) = A' * x. See section Function Interface for details.

Note that when A is symmetric, SVD reduces to eigen decomposition, so you may consider using `eigs()` instead.

### Usage

    svds(A, k, nu = k, nv = k, opts = list(), ...)

    ## S3 method for class 'matrix'
    svds(A, k, nu = k, nv = k, opts = list(), ...)

    ## S3 method for class 'dgeMatrix'
    svds(A, k, nu = k, nv = k, opts = list(), ...)

    ## S3 method for class 'dgCMatrix'
    svds(A, k, nu = k, nv = k, opts = list(), ...)

    ## S3 method for class 'dgRMatrix'
    svds(A, k, nu = k, nv = k, opts = list(), ...)

    ## S3 method for class 'dsyMatrix'
    svds(A, k, nu = k, nv = k, opts = list(), ...)

    ## S3 method for class 'function'
    svds(A, k, nu = k, nv = k, opts = list(), ..., Atrans,
      dim, args = NULL)

### Arguments

`A` | The matrix whose truncated SVD is to be computed.
`k` | Number of singular values requested.
`nu` | Number of left singular vectors to be computed. This must be between 0 and `k`.
`nv` | Number of right singular vectors to be computed. This must be between 0 and `k`.
`opts` | Control parameters related to the computing algorithm. See Details below.
`Atrans` | Only used when `A` is a function. `A` is a function that calculates the matrix multiplication A * x, and `Atrans` is a function that calculates the transpose multiplication A' * x.
`dim` | Only used when `A` is a function, to specify the dimension of the implicit matrix. A vector of length two.
`args` | Only used when `A` is a function. This argument will be passed to the `A` and `Atrans` functions.
`...` | Arguments for specialized S3 function calls, for example `Atrans`, `dim` and `args`.

### Details

The `opts` argument is a list that can supply any of the following parameters:

`ncv`

  Number of Lanzcos basis vectors to use. More vectors will result in faster convergence, but with greater memory use. `ncv` must be satisfy k < ncv <= p where `p = min(m, n)`. Default is `min(p, max(2*k+1, 20))`.

`tol`

  Precision parameter. Default is 1e-10.

`maxitr`

  Maximum number of iterations. Default is 1000.

### Value

A list with the following components:

`d` | A vector of the computed singular values.
`u` | An `m` by `nu` matrix whose columns contain the left singular vectors. If `nu == 0`, `NULL` will be returned.
`v` | An `n` by `nv` matrix whose columns contain the right singular vectors. If `nv == 0`, `NULL` will be returned.
`nconv` | Number of converged singular values.
`niter` | Number of iterations used.
`nops` | Number of matrix-vector multiplications used.

### Function Interface

The matrix A can be specified through two functions with the following definitions

    A <- function(x, args)
    {
        ## should return A %*% x
    }

    Atrans <- function(x, args)
    {
        ## should return t(A) %*% x
    }

They receive a vector `x` as an argument and returns a vector of the proper dimension. These two functions should have the effect of calculating A * x and A' * x respectively, and extra arguments can be passed in through the `args` parameter. In `svds()`, user should also provide the dimension of the implicit matrix through the argument `dim`.

### Author(s)

Yixuan Qiu <http://statr.me>

### See Also

`eigen()`, `svd()`, `eigs()`.

### Examples

    m = 100
    n = 20
    k = 5
    set.seed(111)
    A = matrix(rnorm(m * n), m)

    svds(A, k)
    svds(t(A), k, nu = 0, nv = 3)

    ## Sparse matrices
    library(Matrix)
    A[sample(m * n, m * n / 2)] = 0
    Asp1 = as(A, "dgCMatrix")
    Asp2 = as(A, "dgRMatrix")

    svds(Asp1, k)
    svds(Asp2, k, nu = 0, nv = 0)

    ## Function interface
    Af = function(x, args)
    {
        as.numeric(args %*% x)
    }

    Atf = function(x, args)
    {
        as.numeric(crossprod(args, x))
    }

    svds(Af, k, Atrans = Atf, dim = c(m, n), args = Asp1)

[Package RSpectra version 0.12-0 Index]