Principal components

principal_components() places samples on the principal components of their most variable genes, as DESeq2’s plotPCA does: the top genes of largest variance over the samples, each centred, decomposed by singular values. It takes a samples x genes matrix of log-expression values or a cell type of a cube, whose samples are prepared as edgeR prepares counts for plotMDS. The result, a PrincipalComponents, holds the samples’ coordinates, each component’s share of the variance and the loadings of the genes, and plot_pca() draws it.

Principal components of samples, as DESeq2’s plotPCA computes them.

principal_components() places the samples of a matrix of log-expression values, or of one group (cell type) of a cube, on their principal components (Pearson 1901), as DESeq2’s plotPCA does for its transformed values (Love et al. 2014): from the top genes of largest variance over the samples, each centred on its mean, by the singular value decomposition of that samples x genes matrix, X = U S V’. The coordinates of the samples are U S, the loadings of the genes are V, and the share of the variance that each component explains is its squared singular value over their sum, DESeq2’s percentVar. plot_pca() draws them.

What DESeq2’s help page leaves open was found by running plotPCA 1.46.0 as a black box: it ranks the genes by their variance over the samples, keeps genes of equal variance in their order, takes every gene when ntop exceeds their number, and returns the coordinates of R’s prcomp, whose signs, its help page says, are arbitrary. Here the sign of each component makes the sample with its largest absolute coordinate positive (of near ties, within a relative 1e-9, the first), as plot_mds() orients its dimensions, so that the result does not depend on the order of the genes or the sign of the values.

The values:

A matrix holds one row per sample and one column per gene, finite, such as log-CPM values or the variance-stabilized values that DESeq2’s guide takes. A VoomResult gives its log-CPM values. A cube gives one group’s samples prepared as plot_mds() prepares them, as the edgeR User’s Guide prepares counts for plotMDS: the samples with fewer than min_cells cells or no counts are left out, as limma_voom() leaves them out; the genes are kept by filter_by_expression() (Chen, Lun and Smyth 2016) with the samples as one group; and the values are their log2 counts per million with TMM normalization factors and an average count of 2 added (log_cpm()).

References

Pearson K (1901). On lines and planes of closest fit to systems of points in space. The London, Edinburgh, and Dublin Philosophical Magazine and Journal of Science 2, 559-572. doi:10.1080/14786440109462720

Love MI, Huber W, Anders S (2014). Moderated estimation of fold change and dispersion for RNA-seq data with DESeq2. Genome Biology 15, 550. doi:10.1186/s13059-014-0550-8

Chen Y, Lun ATL, Smyth GK (2016). From reads to genes to pathways: differential expression analysis of RNA-Seq experiments using Rsubread and the edgeR quasi-likelihood pipeline. F1000Research 5, 1438. doi:10.12688/f1000research.8987.2

class cytepool.principal_components.PrincipalComponents(coordinates, variance_explained, loadings, genes, samples, settings)

The samples on their principal components.

Rows of coordinates are the samples used, in the order of samples; columns are the components, in decreasing order of the variance they explain. There are min(n_samples - 1, n_genes) components: the centred values have no more dimensions. The arrays are read-only.

Variables:

• coordinates – (n_samples, n_components) float64, the samples’ coordinates, the centred values times the loadings; DESeq2’s PC1, PC2, … up to sign.

• variance_explained – (n_components,) float64, each component’s share of the total variance of the genes used, summing to 1; DESeq2’s percentVar.

• loadings – (n_genes_used, n_components) float64, the unit vectors of the components over the genes used, in the order of genes.

• genes – (n_genes_used,) positions of the genes used, in decreasing order of their variance: columns of the matrix, or features of the cube.

• samples – One row per sample used: sample_id and, for a cube, the columns of its sample table; for a matrix, the ids "1", "2", … of its rows.

• settings – top, and for a cube its group and min_cells.

Explained in: The cube and its additive layers

property n_components

The number of components.

cytepool.principal_components.principal_components(data, *, group=None, top=_TOP, min_cells=None)

Place samples on the principal components of their most variable genes.

As DESeq2’s plotPCA: the top genes of largest variance over the samples (every gene when there are fewer, genes of equal variance in their order), each centred on its mean over the samples, decomposed by singular values. The module’s docstring describes the values a cube gives and the sign of each component.

Parameters:

• data – (n_samples, n_genes) log-expression values, finite; a VoomResult, whose log-CPM values are used; or a Cube, of which one group’s samples are used.

• group – The group (cell type) of a cube; it may be left out when the cube has one group. Only cubes take it.

• top – The number of genes of largest variance used, at least 1 (DESeq2’s ntop).

• min_cells – The fewest cells a sample of a cube needs in the group, 10 by default as for limma_voom; for a cube that records cell numbers.

Returns:

The coordinates, shares of variance and loadings, with the genes and samples used.

Raises:

• TypeError – If an argument has the wrong type, or is or holds a numpy masked array.

• ValueError – If the values are not finite or not 2-D, fewer than two samples remain, the group of a cube of several groups is not given, group or min_cells is given for data other than a cube, no gene of a cube passes the filter, the genes used do not vary, or an option is out of range.

• KeyError – If the group is not in the cube.

Used in: Pool cells into pseudobulk profiles, Normalization, filtering and sample quality

Explained in: The cube and its additive layers