The svd module

Processes for performing singular value decomposition on a matrix or tensor, and working with the results.

API documentation

class csc.divisi.svd.SVD2DResults(u, v, svals)

This class wraps the U, Sigma (S) and V matrices that result from computing an SVD. An SVD decomposes the matrix A such that A = U*S*(V^T). Both U and V are orthonormal matrices, and S is a diagonal matrix.

This class also provides utility methods to make common SVD-related math easy.

The constructor makes an SVD2DResults object from the matrices created by an SVD. Note that svals is a 1-D vector of sigma values from the SVD.

clear_cache()

Delete all cached tensors from this object.

core

Get the core tensor. The core tensor is the diagonal S matrix from an SVD.

export_svdview(outfn, packed=True, **kw)

Output a tab-separated values file suitable for use with svdview. The data is saved to the file named _outfn_. See the documentation in export_svdview for more information on the denormalize and packed options.

get_ahat(indices)

Get the value of one entry of the reconstructed matrix (A^hat = U * S * V^T).

safe_svals()

Get the sigma values as an array of floats, no matter what they were before.

summarize(k=None, u_only=False, screen_width=80, output=<open file '<stdout>', mode 'w' at 0x2b7cb9b86198>)

For each axis (up to the k-th axis), print the items of the u and v matrices with the largest components on the axis.

u_angles_to(vec)

Return the cosine of the angle between vec and every weighted u vector. This value can be used as a similarity measure that ranges from -1 to 1.

u_dotproducts_with(vec)

Return the dot product of vec with every weighted u vector.

u_similarity(idx1, idx2)

Get the similarity of two rows of the weighted U matrix. Similarity is measured by the dot product of the two u vectors.

v_angles_to(vec)

Return the cosine of the angle between vec and every weighted v vector. This value can be used as a similarity measure that ranges from -1 to 1.

v_dotproducts_with(vec)

Compute the dot product of vec with every weighted v vector.

v_similarity(idx1, idx2)

Get the similarity of two rows of the weighted V matrix. Similarity is measured by the dot product of the two v vectors.

weighted_u

Return U * S, the result of weighting each column of the U matrix by its corresponding sigma value.

weighted_u_vec(idx, default_zeros=False)

Get the weighted u vector with key idx.

If idx is not present and default_zeros is true, returns a vector of zeros.

weighted_v

Return V * S, the result of weighting each column of the V matrix by its corresponding sigma value.

weighted_v_vec(idx, default_zeros=False)

Get the weighted v vector with key idx.

If idx is not present and default_zeros is true, returns a vector of zeros.

class csc.divisi.svd.Reconstructed2DTensor(svd)

This class wraps the results of a 2-D SVD (represented by an SVD2DResults object) and behaves like the Tensor created by multiplying together the U, S and V matrices of the SVD result.

Reconstructed2DTensors require much less storage space than the actual reconstructed tensor. However, access times for a Reconstructed2DTensor are slower, since accessing an entry requires computing a dot product.

The constructor creates a Reconstructed2DTensor from a SVD2DResults object.

class csc.divisi.svd.SVDResults(orig, sub_results)

Stores the results of an arbitrary higher-order SVD. If you are simply taking the SVD of a matrix, you are probably looking for the SVD2DResults class.

self.r is a list of SVD2DResults, one for each unfolding of the tensor.

class csc.divisi.svd.ReconstructedTensor(svd_results)

A ReconstructedTensor is a wrapper around a SVDResults object. The ReconstructedTensor behaves like the tensor constructed by multiplying together the U, Sigma and V matrices (reconstructing the original matrix from its SVD).

ReconstructedTensors require much less storage space than the actual reconstructed tensor would require. However, access times for a ReconstructedTensor are slower, since accessing an entry requires computing a dot product. To mitigate this problem, ReconstructedTensors cache the values of recently-accessed entries.

The constructor creates a ReconstructedTensor from a SVDResults object.

clear_cache()

Clear the cache of recently computed entries. (The cache can become very large, so this may free up a significant amount of memory.)

csc.divisi.svd.incremental_svd(tensor, k=50, niter=100, lrate=0.10000000000000001, logging_interval=None)

Compute SVD of 2-D tensor tensor using an incremental SVD algorithm. This algorithm ignores unknown entries in the sparse tensor instead of treating them as zeros (like Lanczos’ algorithm does). This means that the incremental SVD of a sparse matrix will not necessarily equal the Lanczos’ SVD of the same matrix.

The incremental SVD algorithm performs gradient descent to find the U, V and S matrices that minimize the Root Mean Squared error of the reconstructed matrix.

The optional parameter k is the number of sigma values to retain (default 50). The lrate parameter controls the “learning rate,” a factor that changes the rate of gradient descent (default .1). A larger value means the gradient descent will take larger steps toward its goal. Setting lrate to a “large” value may cause the algorithm to diverge, and will cause a mysterious overflow error. The niter parameter controls the number of steps performed by the gradient descent process (default 100).