Ordinates samples from their feature abundances, optionally after a
normalization such as the centered log ratio (CLR, giving an "Aitchison
PCA"). Gives the same scores, loadings, and variances as stats::prcomp()
on the normalized table, but computes only the first few axes, straight
from sparse input, which takes far less time and memory for large
datasets.
Usage
pca(
counts,
margin = 1L,
norm = "none",
pseudocount = NULL,
n_axes = 3L,
scale = FALSE,
cpus = n_cpus()
)Arguments
- counts
A numeric matrix of count data (samples \(\times\) features). Typically contains absolute abundances (integer counts), though proportions are also accepted.
- margin
The margin containing samples.
1if samples are rows,2if samples are columns. Ignored whencountsis a special object class (e.g.phyloseq). Default:1- norm
Normalize the incoming counts before the PCA. Options are:
'none': No transformation.'percent': Relative abundance (sample abundances sum to 1).'chord': Each sample scaled to unit length (Euclidean norm 1).'hellinger': Square root of relative abundance (the Hellinger transformation).'binary': Presence/absence (each count is either 0 or 1).'clr': Centered log ratio, giving an Aitchison PCA.'rclr': Robust centered log ratio. Zeros stay 0.'log': Log relative abundance (log-TSS), withpseudocountadded to every value first.
Default:
'none'.- pseudocount
Value added to counts to handle zeros when
norm = 'clr'or'log'. Ignored for other normalization methods. See Pseudocount section.- n_axes
The number of axes to compute. Default:
3- scale
Scale each feature to unit variance (after
norm, before the PCA), as inprcomp(scale. = TRUE). This gives every feature equal weight, so that a PCA of the correlation matrix rather than the covariance matrix results. Default:FALSE- cpus
How many parallel processing threads should be used. The default,
n_cpus(), is the CPU cores this R process may use, within any limits set on it. Results are the same for anycpus.
Value
A numeric matrix with one row per sample and one column per axis,
named "PC1", "PC2", etc., as described in "Ordination result"
below. Its attributes are:
method:"pca".eig: The variance of each axis:prcomp()'ssdev^2.prop: The proportion of the total variance that each axis explains,eig / trace.trace: The total variance: the sum of all features' variances (afternormandscale), which is also the sum of all axes'eig.loadings: A matrix with one row per feature and one column per axis: the unit-length principal axes,prcomp()'srotation.
Details
Method
With \(Z\) the normalized table (samples in rows), \(J\) the centering
matrix, and \(D\) the diagonal matrix of the features' standard
deviations (or the identity matrix when scale = FALSE), PCA is the
singular value decomposition \(JZD^{-1} = USV^T\). The scores are
\(US\), the loadings \(V\), and each axis's variance (eig) is
\(s^2 / (n - 1)\), for \(n\) samples.
prcomp() builds the whole centered table and decomposes it in full.
pca() finds only the first n_axes axes, by block Lanczos iteration, which
only needs products of the table with a few vectors at a time. Those are
computed in parallel from the non-zero counts alone: the zeros of each
sample all share one value after normalization (0, or
\(\log(pseudocount)\) minus the sample's mean log for norm = 'clr'),
and centering only subtracts each feature's mean, so a sparse table is
never made dense.
Relation to pcoa()
The scores are the same as those of pcoa() on the Euclidean distances
between the normalized samples: pca(counts) and
pcoa(euclidean(counts)), or pca(counts, norm = 'clr') and
pcoa(aitchison(counts)), give the same coordinates. PCoA's eigenvalues
are \(s^2\), so pca()'s eig is pcoa()'s divided by \(n - 1\);
prop is the same for both. What pca() adds is the loadings: how much
each feature contributes to each axis, e.g. for a biplot.
Robust Aitchison PCA
norm = 'rclr' with pca() is a plain PCA of the rclr-transformed table,
with its zeros left as 0. DEICODE and gemelli's Robust Aitchison PCA
instead treat those zeros as missing values and fill them in by low-rank
matrix completion (OptSpace) before the decomposition, so their results
differ.
Axis signs and reproducibility
A principal axis's sign is arbitrary, so different software can return
mirror images of the same axis. As pcoa() does, pca() flips each axis
so that its largest score in absolute value is positive, and flips its
loadings to match. Results are identical from run to run and for any
number of cpus.
n_axes larger than the number of samples minus one, or the number of
features, is reduced to the smaller of those. Axes with variances at
rounding-error level, below sqrt(.Machine$double.eps) times the first
one, are dropped with a warning. With scale = TRUE, features with
constant values (such as features absent from every sample) are left out,
where prcomp() would stop with an error.
Ordination result
Every ordination function (pcoa(), pca(), rpca(), dbrda(), capda(),
capscale(), mds(), nmds(), isomap(), tsne(), umap(), and so
dist_ord()) returns the same kind of
object: a numeric matrix with one row per sample and one column per
axis, so that it can go straight into a data frame. Rows are
named after the samples, when the input has names. Columns are named
after the method: "PCoA1", "PC1", "RPCA1", "dbRDA1" or "CAP1"
(then "MDS1" for unconstrained axes), "MDS1", "NMDS1",
"Isomap1", "TSNE1", "UMAP1", and so on.
Its attributes always begin with these three, in this order, each with one value per column:
method: The method's ID, e.g."pcoa"or"nmds".eig: Each axis's eigenvalue, on the method's own scale:pcoa()andisomap()give the eigenvalues of Gower's centered matrix (sums of squares);pca()andrpca()give variances, which arepcoa()'s divided by \(n - 1\) for \(n\) samples; anddbrda()andcapscale()followvegan, which also divides by \(n - 1\) when any distance is 4 or more.NAformds(),nmds(),tsne(), andumap(), which have no eigenvalues.prop: The proportion of the total variance (or inertia) that each axis explains. Unlikeeig, it is comparable between methods, so use it to label axes.NAwhere it isn't defined.
Attributes particular to the method follow them, and last display,
with the ordination's title for plot() and print(): the method's
name, and for the methods that take distances, the distance matrix's
title, such as "Principal Coordinates Analysis of Bray-Curtis
Dissimilarity" (see ecodive_display). The matrix has class
"ecodive_ord" (as well as "matrix"), so that print() lists the
other attributes by name rather than in full, and plot() draws the
samples on the first two axes, labelled from the attributes, with any
loadings, constraints and centroids on top (see plot.ecodive_ord()).
plot(ord, "Species", iris) colours the samples by a column of
metadata. Subsetting with [, or as.data.frame(), gives a plain
matrix or data frame without the attributes.
Input Types
The counts parameter is designed to accept a simple numeric matrix, but
seamlessly supports objects from the following biological data packages:
phyloseqrbiomSummarizedExperimentTreeSummarizedExperiment
For large datasets, standard matrix operations may be slow. See
vignette('performance') for details on using optimized formats
(e.g. sparse matrices) and parallel processing.
Pseudocount
The pseudocount parameter is only relevant when norm = 'clr'
or norm = 'log'.
Zeros are undefined in the centered log-ratio (CLR) transformation and
in the log of proportions. If norm is 'clr' or
'log', pseudocount is NULL (the default), and
zeros are detected, the function uses half the minimum non-zero value
(min(x[x>0]) / 2) and issues a warning.
To suppress the warning, provide an explicit value (e.g., 1), or
replace the zeros first with replace_zeros(), whose
result needs no pseudocount.
Why this matters: The choice of pseudocount is not neutral; it acts as a weighting factor that can significantly distort downstream results, especially for sparse datasets. See Gloor et al. (2017) and Kaul et al. (2017) for open-access discussions on the mathematical implications, or Costea et al. (2014) for the impact on community clustering.
See aitchison for references.
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(11), 559-572. doi:10.1080/14786440109462720
Aitchison, J. (1983). Principal component analysis of compositional data. Biometrika, 70(1), 57-65. doi:10.1093/biomet/70.1.57
Examples
ord <- pca(iris[, 1:4])
plot(ord, 'Species', iris)
ord
#> # A matrix: 150 samples × 3 axes
#> # Principal Component Analysis
#> # % of variance: 92.5, 5.3, 1.7
#> PC1 PC2 PC3
#> 1 -2.68 0.319 -0.0279
#> 2 -2.71 -0.177 -0.21
#> 3 -2.89 -0.145 0.0179
#> 4 -2.75 -0.318 0.0316
#> 5 -2.73 0.327 0.0901
#> 6 -2.28 0.741 0.169
#> 7 -2.82 -0.0895 0.258
#> 8 -2.63 0.163 -0.0219
#> 9 -2.89 -0.578 0.0208
#> 10 -2.67 -0.114 -0.198
#> # … 140 more samples
#> # Use print(x, n = ...) to see more samples
#> # Attributes: method, eig, prop, trace, loadings
str(ord)
#> 'ecodive_ord' num [1:150, 1:3] -2.68 -2.71 -2.89 -2.75 -2.73 ...
#> - attr(*, "dimnames")=List of 2
#> ..$ : NULL
#> ..$ : chr [1:3] "PC1" "PC2" "PC3"
#> - attr(*, "method")= chr "pca"
#> - attr(*, "eig")= num [1:3] 4.2282 0.2427 0.0782
#> - attr(*, "prop")= num [1:3] 0.9246 0.0531 0.0171
#> - attr(*, "trace")= num 4.57
#> - attr(*, "loadings")= num [1:4, 1:3] 0.3614 -0.0845 0.8567 0.3583 0.6566 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:4] "Sepal.Length" "Sepal.Width" "Petal.Length" "Petal.Width"
#> .. ..$ : chr [1:3] "PC1" "PC2" "PC3"
#> - attr(*, "display")=List of 1
#> ..$ title: chr "Principal Component Analysis"
