irlba Namespace Reference

Implements IRLBA for approximate SVD. More...

Classes
class	AdjointWorkspace
	Workspace class for multiplying a transposed Matrix. More...
class	CenteredAdjointWorkspace
	Workspace class for multiplying a transposed CenteredMatrix. More...
class	CenteredMatrix
	Deferred centering of a matrix. More...
class	CenteredRealizeWorkspace
	Workspace class for realizing a CenteredMatrix. More...
class	CenteredWorkspace
	Workspace class for multiplying a CenteredMatrix. More...
class	EigenThreadScope
	Restrict the number of available threads for Eigen. More...
class	Matrix
	Interface for a matrix to use in compute(). More...
struct	Options
	Options for running IRLBA in compute() and pca(). More...
class	ParallelSparseAdjointWorkspace
	Workspace for multiplication of a transposed ParallelSparseMatrix. More...
class	ParallelSparseMatrix
	Sparse matrix with customizable parallelization. More...
class	ParallelSparseRealizeWorkspace
	Workspace for realizing a ParallelSparseMatrix. More...
class	ParallelSparseWorkspace
	Workspace for multiplication of a ParallelSparseMatrix. More...
struct	PcaResults
	Results of the IRLBA-based PCA by pca(). More...
class	RealizeWorkspace
	Workspace class for realizing a Matrix. More...
struct	Results
	Results of the IRLBA-based SVD by compute(). More...
class	ScaledAdjointWorkspace
	Workspace class for multiplying a transposed ScaledMatrix. More...
class	ScaledMatrix
	Deferred scaling of a matrix. More...
class	ScaledRealizeWorkspace
	Workspace class for realizing a ScaledMatrix. More...
class	ScaledWorkspace
	Workspace class for multiplying a ScaledMatrix. More...
class	SimpleAdjointWorkspace
	Workspace class for multiplying a transposed SimpleMatrix. More...
class	SimpleMatrix
	A Matrix-compatible wrapper around a "simple" matrix. More...
class	SimpleRealizeWorkspace
	Workspace class for realizing a SimpleMatrix. More...
class	SimpleWorkspace
	Workspace class for multiplying a SimpleMatrix. More...
class	Workspace
	Workspace class for multiplying a Matrix. More...

Functions
template<class Matrix_ , class EigenMatrix_ , class EigenVector_ >
std::pair< bool, int >	compute (const Matrix_ &matrix, const Eigen::Index number, EigenMatrix_ &outU, EigenMatrix_ &outV, EigenVector_ &outD, const Options< EigenVector_ > &options)
template<class InputEigenMatrix_ , class OutputEigenMatrix_ , class EigenVector_ >
std::pair< bool, int >	compute_simple (const InputEigenMatrix_ &matrix, Eigen::Index number, OutputEigenMatrix_ &outU, OutputEigenMatrix_ &outV, EigenVector_ &outD, const Options< EigenVector_ > &options)
template<class EigenMatrix_ = Eigen::MatrixXd, class EigenVector_ = Eigen::VectorXd, class Matrix_ >
Results< EigenMatrix_, EigenVector_ >	compute (const Matrix_ &matrix, Eigen::Index number, const Options< EigenVector_ > &options)
template<class OutputEigenMatrix_ = Eigen::MatrixXd, class EigenVector_ = Eigen::VectorXd, class InputEigenMatrix_ >
Results< OutputEigenMatrix_, EigenVector_ >	compute_simple (const InputEigenMatrix_ &matrix, Eigen::Index number, const Options< EigenVector_ > &options)
template<typename Task_ , class Run_ >
void	parallelize (Task_ num_tasks, Run_ run_task)
template<class InputEigenMatrix_ , class OutputEigenMatrix_ , class EigenVector_ >
std::pair< bool, int >	pca (const InputEigenMatrix_ &matrix, bool center, bool scale, Eigen::Index number, OutputEigenMatrix_ &scores, OutputEigenMatrix_ &rotation, EigenVector_ &variances, const Options< EigenVector_ > &options)
template<class OutputEigenMatrix_ = Eigen::MatrixXd, class EigenVector_ = Eigen::VectorXd, class InputEigenMatrix_ >
PcaResults< OutputEigenMatrix_, EigenVector_ >	pca (const InputEigenMatrix_ &matrix, bool center, bool scale, Eigen::Index number, const Options< EigenVector_ > &options)

Detailed Description

Implements IRLBA for approximate SVD.

Function Documentation

compute() [1/2]

template<class Matrix_ , class EigenMatrix_ , class EigenVector_ >

std::pair< bool, int > irlba::compute	(	const Matrix_ &	matrix,
		const Eigen::Index	number,
		EigenMatrix_ &	outU,
		EigenMatrix_ &	outV,
		EigenVector_ &	outD,
		const Options< EigenVector_ > &	options )

Implements the Implicitly Restarted Lanczos Bidiagonalization Algorithm (IRLBA) for fast truncated singular value decomposition. This is heavily derived from the C code in the irlba package, with refactoring into C++ to use Eigen instead of LAPACK for much of the matrix algebra.

Template Parameters

Matrix_	Class satisfying the Matrix<EigenVector_, EigenMatrix_> interface.
EigenMatrix_	A dense floating-point Eigen::Matrix class to store the output.
EigenVector_	A floating-point Eigen::Vector class to store the output, typically of the same scalar type as EigenMatrix_.

Parameters

[in]	matrix	Input matrix.
	number	Number of singular triplets to obtain. The returned number of triplets may be lower, see Options::cap_number for details.
[out]	outU	Output matrix containing the left singular vectors corresponding to the largest singular values. Each column corresponds to a left singular vector, of which there are number (or less, depending on Options::cap_number). The number of rows is equal to the number of rows in mat.
[out]	outV	Output matrix containing the right singular vectors corresponding to the largest singular values. Each column corresponds to a right singular vector, of which there are number (or less, depending on Options::cap_number). The number of rows is equal to the number of columns in mat.
[out]	outD	Output vector containing the largest singular values, ordered by decreasing size. This has length equal to number (or lower, depending on Options::cap_number).
	options	Further options.

Returns

A pair where the first entry indicates whether the algorithm converged, and the second entry indicates the number of restart iterations performed.

compute() [2/2]

template<class EigenMatrix_ = Eigen::MatrixXd, class EigenVector_ = Eigen::VectorXd, class Matrix_ >

Results< EigenMatrix_, EigenVector_ > irlba::compute	(	const Matrix_ &	matrix,
		Eigen::Index	number,
		const Options< EigenVector_ > &	options )

Convenient overload of compute() that allocates memory for the output matrices of the SVD.

Template Parameters

EigenMatrix_	A dense floating-point Eigen::Matrix class to store the output.
EigenVector_	A floating-point Eigen::Vector class for the output, typically of the same scalar type as EigenMatrix_.
Matrix_	Class satisfying the Matrix<EigenVector_, EigenMatrix_> interface.

Parameters

[in]	matrix	Input matrix.
	number	Number of singular triplets to obtain.
	options	Further options.

Returns

A Results object containing the singular vectors and values, as well as some statistics on convergence.

compute_simple() [1/2]

template<class OutputEigenMatrix_ = Eigen::MatrixXd, class EigenVector_ = Eigen::VectorXd, class InputEigenMatrix_ >

Results< OutputEigenMatrix_, EigenVector_ > irlba::compute_simple	(	const InputEigenMatrix_ &	matrix,
		Eigen::Index	number,
		const Options< EigenVector_ > &	options )

Convenient overload of compute() that accepts an Eigen matrix directly.

Template Parameters

InputEigenMatrix_	An Eigen matrix class containing the input data.
OutputEigenMatrix_	A dense floating-point Eigen::Matrix class for the output.
EigenVector_	A floating-point Eigen::Vector class for the output, typically of the same scalar type as OutputEigenMatrix_.
Matrix_	Class satisfying the Matrix<EigenVector_, EigenMatrix_> interface.

Parameters

[in]	matrix	Input matrix.
	number	Number of singular triplets to obtain.
	options	Further options.

Returns

A Results object containing the singular vectors and values, as well as some statistics on convergence.

compute_simple() [2/2]

template<class InputEigenMatrix_ , class OutputEigenMatrix_ , class EigenVector_ >

std::pair< bool, int > irlba::compute_simple	(	const InputEigenMatrix_ &	matrix,
		Eigen::Index	number,
		OutputEigenMatrix_ &	outU,
		OutputEigenMatrix_ &	outV,
		EigenVector_ &	outD,
		const Options< EigenVector_ > &	options )

Convenient overload of compute() that accepts an Eigen matrix directly.

Template Parameters

InputEigenMatrix_	An Eigen matrix class containing the input data.
OutputEigenMatrix_	A dense floating-point Eigen::Matrix class to store the output.
EigenVector_	A floating-point Eigen::Vector class to store the output, typically of the same scalar type as EigenMatrix_.

Parameters

[in]	matrix	Input matrix.
	number	Number of singular triplets to obtain. The returned number of triplets may be lower, see Options::cap_number for details.
[out]	outU	Output matrix containing the left singular vectors corresponding to the largest singular values. Each column corresponds to a left singular vector, of which there are number (or less, depending on Options::cap_number). The number of rows is equal to the number of rows in mat.
[out]	outV	Output matrix containing the right singular vectors corresponding to the largest singular values. Each column corresponds to a right singular vector, of which there are number (or less, depending on Options::cap_number). The number of rows is equal to the number of columns in mat.
[out]	outD	Output vector containing the largest singular values, ordered by decreasing size. This has length equal to number (or lower, depending on Options::cap_number).
	options	Further options.

Returns

A pair where the first entry indicates whether the algorithm converged, and the second entry indicates the number of restart iterations performed.

parallelize()

template<typename Task_ , class Run_ >

void irlba::parallelize	(	Task_	num_tasks,
		Run_	run_task )

Template Parameters

Task_	Integer type for the number of tasks.
Run_	Function to execute each task.

Parameters

num_tasks	Number of tasks. This is equal to the number of threads in the context of ParallelSparseMatrix.
run_task	Function to execute each task within its own worker.

By default, this is an alias to subpar::parallelize_simple(). However, if the IRLBA_CUSTOM_PARALLEL function-like macro is defined, it is called instead. Any user-defined macro should accept the same arguments as subpar::parallelize_simple().

pca() [1/2]

template<class OutputEigenMatrix_ = Eigen::MatrixXd, class EigenVector_ = Eigen::VectorXd, class InputEigenMatrix_ >

PcaResults< OutputEigenMatrix_, EigenVector_ > irlba::pca	(	const InputEigenMatrix_ &	matrix,
		bool	center,
		bool	scale,
		Eigen::Index	number,
		const Options< EigenVector_ > &	options )

Convenient overload of pca() that allocates memory for the output matrices of the PCA.

Template Parameters

InputEigenMatrix_	An Eigen matrix class containing the input data.
OutputEigenMatrix_	A dense floating-point Eigen::Matrix class for the output.
EigenVector_	A floating-point Eigen::Vector class for the output, typically of the same scalar type as EigenMatrix_.

Parameters

[in]	matrix	Input matrix where rows are observations and columns are features.
	center	Should the matrix be centered by column? This should be set to true if the matrix is not already centered.
	scale	Should the matrix be scaled to unit variance for each column?
	number	Number of singular triplets to obtain.
	options	Further options.

Returns

A Results object containing the singular vectors and values, as well as some statistics on convergence.

pca() [2/2]

template<class InputEigenMatrix_ , class OutputEigenMatrix_ , class EigenVector_ >

std::pair< bool, int > irlba::pca	(	const InputEigenMatrix_ &	matrix,
		bool	center,
		bool	scale,
		Eigen::Index	number,
		OutputEigenMatrix_ &	scores,
		OutputEigenMatrix_ &	rotation,
		EigenVector_ &	variances,
		const Options< EigenVector_ > &	options )

Perform a principal components analysis (PCA) using IRLBA for the underlying SVD. This applies deferred centering and scaling via the CenteredMatrix and ScaledMatrix classes, respectively.

Template Parameters

InputEigenMatrix_	An Eigen matrix class containing the input data.
OutputEigenMatrix_	A dense floating-point Eigen::Matrix class for the output.
EigenVector_	A floating-point Eigen::Vector class for the output, typically of the same scalar type as OutputEigenMatrix_.

Parameters

[in]	matrix	Input matrix where rows are observations and columns are features.
	center	Should the matrix be centered by column? This should be set to true if the matrix is not already centered.
	scale	Should the matrix be scaled to unit variance for each column?
	number	Number of principal components to obtain.
[out]	scores	Output matrix for the principal component scores. Each row corresponds to an observation while each column corresponds to a principal component. On output, the number of rows is equal to the number of columns in matrix, while the number of columns is equal to number (or less, if Options::cap_number is applied).
[out]	rotation	Output matrix in which to store the rotation matrix. Each row corresponds to an feature while each column corresponds to a principal component. On output, the number of rows is equal to the number of rows in matrix, while the number of columns is equal to number (or less, if Options::cap_number is applied).
[out]	variances	Vector to store the variance explained by each principal component. On output, the length of this vector is equal to number (or less, if Options::cap_number is applied).
	options	Further options.

Returns

A pair where the first entry indicates whether the algorithm converged, and the second entry indicates the number of restart iterations performed.

Centering is performed by subtracting each element of center from the corresponding column of mat. Scaling is performed by dividing each column of mat by the corresponding element of scale (after any centering has been applied). Note that scale=true requires center=true to guarantee unit variance along each column. No scaling is performed when the variance of a column is zero, so as to avoid divide-by-zero errors.