Helper functions for including node embeddings in formulas

Quickly compute top rank singular vectors of a matrix A and return them in a matrix. Especially useful in formulas in regression objects.

Usage

U(A, rank, ...)

US(A, rank, ...)

V(A, rank, ...)

VS(A, rank, ...)

Arguments

A

A matrix() or Matrix::Matrix() object.

rank

Rank of desired decomposition.

...

Arguments passed on to irlba::irlba

nv

number of right singular vectors to estimate.

nu

number of left singular vectors to estimate (defaults to nv).

maxit

maximum number of iterations.

work

working subspace dimension, larger values can speed convergence at the cost of more memory use.

reorth

if TRUE, apply full reorthogonalization to both SVD bases, otherwise only apply reorthogonalization to the right SVD basis vectors; the latter case is cheaper per iteration but, overall, may require more iterations for convergence. Automatically TRUE when fastpath=TRUE (see below).

tol

convergence is determined when \(\|A^TU - VS\| < tol\|A\|\), and when the maximum relative change in estimated singular values from one iteration to the next is less than svtol = tol (see svtol below), where the spectral norm ||A|| is approximated by the largest estimated singular value, and U, V, S are the matrices corresponding to the estimated left and right singular vectors, and diagonal matrix of estimated singular values, respectively.

v

optional starting vector or output from a previous run of irlba used to restart the algorithm from where it left off (see the notes).

right_only

logical value indicating return only the right singular vectors (TRUE) or both sets of vectors (FALSE). The right_only option can be cheaper to compute and use much less memory when nrow(A) >> ncol(A) but note that obtained solutions typically lose accuracy due to lack of re-orthogonalization in the algorithm and that right_only = TRUE sets fastpath = FALSE (only use this option for really large problems that run out of memory and when nrow(A) >> ncol(A)). Consider increasing the work option to improve accuracy with right_only=TRUE.

verbose

logical value that when TRUE prints status messages during the computation.

scale

optional column scaling vector whose values divide each column of A; must be as long as the number of columns of A (see notes).

center

optional column centering vector whose values are subtracted from each column of A; must be as long as the number of columns of A and may not be used together with the deflation options below (see notes).

shift

optional shift value (square matrices only, see notes).

mult

DEPRECATED optional custom matrix multiplication function (default is %*%, see notes).

fastpath

try a fast C algorithm implementation if possible; set fastpath=FALSE to use the reference R implementation. See the notes for more details.

svtol

additional stopping tolerance on maximum allowed absolute relative change across each estimated singular value between iterations. The default value of this parameter is to set it to tol. You can set svtol=Inf to effectively disable this stopping criterion. Setting svtol=Inf allows the method to terminate on the first Lanczos iteration if it finds an invariant subspace, but with less certainty that the converged subspace is the desired one. (It may, for instance, miss some of the largest singular values in difficult problems.)

smallest

set smallest=TRUE to estimate the smallest singular values and associated singular vectors. WARNING: this option is somewhat experimental, and may produce poor estimates for ill-conditioned matrices.

Details

In all cases, computes a top-rank decomposition of A, such that \(A \approx U S V^T\).

• U returns \(U\)

• US returns \(U S^{1/2}\)

• V returns \(V\)

• VS returns \(V S^{1/2}\)

See also

nodelm, vsp_specials