scran_pca Namespace Reference

Principal component analysis on single-cell data. More...

Classes
struct	BlockedPcaOptions
	Options for blocked_pca(). More...
struct	BlockedPcaResults
	Results of blocked_pca(). More...
struct	SimplePcaOptions
	Options for simple_pca(). More...
struct	SimplePcaResults
	Results of simple_pca(). More...

Functions
template<typename Value_ , typename Index_ , typename EigenMatrix_ , class EigenVector_ >
void	simple_pca (const tatami::Matrix< Value_, Index_ > &mat, const SimplePcaOptions &options, SimplePcaResults< EigenMatrix_, EigenVector_ > &output)
template<typename EigenMatrix_ = Eigen::MatrixXd, class EigenVector_ = Eigen::VectorXd, typename Value_ , typename Index_ >
SimplePcaResults< EigenMatrix_, EigenVector_ >	simple_pca (const tatami::Matrix< Value_, Index_ > &mat, const SimplePcaOptions &options)
template<typename Value_ , typename Index_ , typename Block_ , typename EigenMatrix_ , class EigenVector_ >
void	blocked_pca (const tatami::Matrix< Value_, Index_ > &mat, const Block_ *block, const BlockedPcaOptions &options, BlockedPcaResults< EigenMatrix_, EigenVector_ > &output)
template<typename EigenMatrix_ = Eigen::MatrixXd, class EigenVector_ = Eigen::VectorXd, typename Value_ , typename Index_ , typename Block_ >
BlockedPcaResults< EigenMatrix_, EigenVector_ >	blocked_pca (const tatami::Matrix< Value_, Index_ > &mat, const Block_ *block, const BlockedPcaOptions &options)

Detailed Description

Principal component analysis on single-cell data.

Function Documentation

blocked_pca() [1/2]

template<typename EigenMatrix_ = Eigen::MatrixXd, class EigenVector_ = Eigen::VectorXd, typename Value_ , typename Index_ , typename Block_ >

BlockedPcaResults< EigenMatrix_, EigenVector_ > scran_pca::blocked_pca	(	const tatami::Matrix< Value_, Index_ > &	mat,
		const Block_ *	block,
		const BlockedPcaOptions &	options )

Overload of blocked_pca() that allocates memory for the output.

Template Parameters

EigenMatrix_	A floating-point column-major Eigen::Matrix class.
EigenVector_	A floating-point Eigen::Vector class.
Value_	Type of the matrix data.
Index_	Integer type for the indices.
Block_	Integer type for the blocking factor.

Parameters

[in]	mat	Input matrix. Columns should contain cells while rows should contain genes. Matrix entries are typically log-expression values.
[in]	block	Pointer to an array of length equal to the number of cells, containing the block assignment for each cell. Each assignment should be an integer in \([0, N)\) where \(N\) is the number of blocks.
	options	Further options.

Returns

Results of the PCA on the residuals.

blocked_pca() [2/2]

template<typename Value_ , typename Index_ , typename Block_ , typename EigenMatrix_ , class EigenVector_ >

void scran_pca::blocked_pca	(	const tatami::Matrix< Value_, Index_ > &	mat,
		const Block_ *	block,
		const BlockedPcaOptions &	options,
		BlockedPcaResults< EigenMatrix_, EigenVector_ > &	output )

As discussed in simple_pca(), we would like to extract the top principal components from a single-cell dataset for downstream cell-based procedures like clustering. In the presence of a blocking factor (e.g., batches, samples), we want to ensure that the PCA is not driven by uninteresting differences between blocks of cells. To achieve this, blocked_pca() centers the expression of each gene in each blocking level and uses the residuals for PCA. This means that the gene-gene covariance matrix will only contain variation within each batch, ensuring that the top rotation vectors/principal components capture biological heterogeneity instead of inter-block differences.

The BlockedPcaOptions::components_from_residuals option determines exactly how the PC scores are calculated:

• If true (the default), the PC scores are computed from the matrix of residuals. This yields a low-dimensional space where inter-block differences have been removed, assuming that all blocks have the same subpopulation composition and the inter-block differences are consistent for all cell subpopulations. Under these assumptions, we could use these components for downstream analysis without any concern for block-wise effects.
• If false, the rotation vectors are first computed from the matrix of residuals. To obtain PC scores, each cell is then projected onto the associated subspace using its original expression values. This approach ensures that inter-block differences do not contribute to the PCA but does not attempt to explicitly remove them.

In complex datasets, the assumptions mentioned above for true do not hold, and more sophisticated batch correction methods like MNN correction are required. Some of these methods accept a low-dimensional embedding of cells that can be created as described above with false.

blocked_pca() will adjust the contribution from blocks of cells so that each block contributes more or less equally to the PCA. This ensures that the definition of the axes of maximum variance are not dominated by the largest block, potentially masking interesting variation in the smaller blocks. blocked_pca() scales the expression values for each block so that each "sufficiently large" block contributes equally to the gene-gene covariance matrix and thus the rotation vectors. (See BlockedPcaOptions::block_weight_policy for the choice of weighting scheme.) The vector of residuals for each cell - or the original expression values, if BlockedPcaOptions::components_from_residuals = false - is then projected to the subspace defined by these rotation vectors to obtain that cell's PC scores.

Internally, blocked_pca() defers the residual calculation until the matrix multiplication steps within IRLBA. This yields the same results as the naive calculation of residuals but is much faster as it can take advantage of efficient sparse operations.

Template Parameters

Value_	Type of the matrix data.
Index_	Integer type for the indices.
Block_	Integer type for the blocking factor.
EigenMatrix_	A floating-point column-major Eigen::Matrix class.
EigenVector_	A floating-point Eigen::Vector class.

Parameters

[in]	mat	Input matrix. Columns should contain cells while rows should contain genes. Matrix entries are typically log-expression values.
[in]	block	Pointer to an array of length equal to the number of cells, containing the block assignment for each cell. Each assignment should be an integer in \([0, N)\) where \(N\) is the number of blocks.
	options	Further options.
[out]	output	On output, the results of the PCA on the residuals. This can be re-used across multiple calls to blocked_pca().

simple_pca() [1/2]

template<typename EigenMatrix_ = Eigen::MatrixXd, class EigenVector_ = Eigen::VectorXd, typename Value_ , typename Index_ >

SimplePcaResults< EigenMatrix_, EigenVector_ > scran_pca::simple_pca	(	const tatami::Matrix< Value_, Index_ > &	mat,
		const SimplePcaOptions &	options )

Overload of simple_pca() that allocates memory for the output.

Template Parameters

EigenMatrix_	A floating-point column-major Eigen::Matrix class.
EigenVector_	A floating-point Eigen::Vector class.
Value_	Type of the matrix data.
Index_	Integer type for the indices.

Parameters

[in]	mat	The input matrix. Columns should contain cells while rows should contain genes. Matrix entries are typically log-expression values.
	options	Further options.

Returns

Results of the PCA.

simple_pca() [2/2]

template<typename Value_ , typename Index_ , typename EigenMatrix_ , class EigenVector_ >

void scran_pca::simple_pca	(	const tatami::Matrix< Value_, Index_ > &	mat,
		const SimplePcaOptions &	options,
		SimplePcaResults< EigenMatrix_, EigenVector_ > &	output )

Principal components analysis (PCA) for compression and denoising of single-cell expression data.

The premise behind PCA is that most of the variation in the dataset is driven by biological differences between subpopulations that drive coordinated changes across multiple genes in the same pathways. In contrast, technical noise is random and not synchronized across any one axis in the high-dimensional space. This suggests that the earlier principal components (PCs) should be enriched for biological heterogeneity while the later PCs capture random noise.

Our aim is to reduce the size of the data and eliminate noise by only using the earlier PCs for downstream cell-based analyses (e.g., neighbor detection, clustering). Most practitioners will keep the first 10-50 PCs, though the exact choice is fairly arbitrary - see SimplePcaOptions::number to specify the number of PCs. As we are only interested in the top PCs, we can use approximate algorithms for faster computation, in particular IRLBA.

Template Parameters

Value_	Type of the matrix data.
Index_	Integer type for the indices.
EigenMatrix_	A floating-point column-major Eigen::Matrix class.
EigenVector_	A floating-point Eigen::Vector class.

Parameters

[in]	mat	The input matrix. Columns should contain cells while rows should contain genes. Matrix entries are typically log-expression values.
	options	Further options.
[out]	output	On output, the results of the PCA on mat. This can be re-used across multiple calls to simple_pca().