Runs any of ecodive's ordination methods that take a count table by name,
as dist_ord() does for the methods that take distances.
Arguments
- counts
A numeric matrix of count data (samples \(\times\) features). Typically contains absolute abundances (integer counts), though proportions are also accepted.
- method
The name of an ordination method:
"ca","cca","dpcoa","lda","oplsda","pca","plsda","rda","rpca", or"rpca_phylo". Flexible matching is supported (see below). Programmatic access vialist_count_ords().- ...
Further arguments for the method's function, such as
n_axes,margin,cpus,pca()'snorm,pseudocount, andscale, orrda()'s andcca()'sgroups,data, andformula, orlda()'s,plsda()'s andoplsda()'sgroupsanddata, orrpca_phylo()'stree, ordpcoa()'streeortaxa_dm. Each method keeps its own defaults; seeca(),cca(),dpcoa(),lda(),oplsda(),pca(),plsda(),rda(),rpca(), andrpca_phylo().seedis ignored by the methods that have no random parts (all butcca(), whose adjusted \(R^2\) is found by permutation), so the same arguments can be given to every method.
Value
The method's result, as described in "Ordination result" below.
count_ord(counts, 'pca', ...) is the same as pca(counts, ...).
Details
List of Ordination Methods
| Option / Function Name | Method Name |
ca | Correspondence Analysis (CA) |
cca | Canonical Correspondence Analysis (CCA), constrained |
dpcoa | Double Principal Coordinate Analysis (DPCoA) (needs tree or taxa_dm) |
lda | Linear Discriminant Analysis (LDA), supervised |
oplsda | Orthogonal PLS Discriminant Analysis (OPLS-DA), supervised |
pca | Principal Component Analysis (PCA) |
plsda | Partial Least Squares Discriminant Analysis (PLS-DA), supervised |
rda | Redundancy Analysis (RDA), constrained |
rpca | Robust Aitchison PCA |
rpca_phylo | Phylogenetic Robust Aitchison PCA (needs tree) |
rda is constrained by sample metadata, given as further arguments:
count_ord(counts, 'rda', 'treatment', meta) is
rda(counts, 'treatment', meta). Without them, it is a PCA. cca is
constrained the same way; without constraints, it is a correspondence
analysis. lda, plsda and oplsda need the groups to separate, given
the same way: count_ord(counts, 'plsda', 'treatment', meta) is
plsda(counts, 'treatment', meta). oplsda takes n_orthogonal rather
than n_axes. rpca_phylo needs a phylogenetic tree:
count_ord(counts, 'rpca_phylo', tree = tree), and so does dpcoa
(or the dissimilarities among the taxa, taxa_dm):
count_ord(counts, 'dpcoa', tree = tree).
Methods that ordinate distances, such as pcoa() and nmds(), are run
by dist_ord().
Flexible name matching
Case insensitive and partial matching, ignoring anything but letters. E.g.
method = 'PCA' or 'principal comp' selects pca. Common other names
also work: 'prcomp' for pca; 'redundancy analysis', 'tbRDA', or
'transformation-based RDA' for rda; 'canonical correspondence analysis' or 'constrained correspondence analysis' for cca;
'correspondence analysis' for ca; and 'robust PCA', 'DEICODE',
or 'gemelli' for rpca; 'phylogenetic RPCA', 'phylo-RPCA', or
'phylogenetic DEICODE' for rpca_phylo; 'DPCoA' or 'double principal coordinate analysis' for dpcoa; and 'PLS-DA', 'PLS', or 'partial least squares discriminant analysis' for plsda; and 'LDA' or 'linear discriminant analysis' for lda; and 'OPLS-DA', 'OPLS', or
'orthogonal PLS-DA' for oplsda. 'CA' selects ca, and
'CCA' selects cca.
Finished code should always use the full primary option name to avoid ambiguity with future additions to the list of methods.
Same names in other packages
vegan::pca(), vegan::rda(), vegan::cca() and vegan::ca() (and
ca::ca()) share their names with ecodive's pca(), rda(), cca()
and ca(), as ade4::dpcoa() does with dpcoa(), mixOmics::plsda() and caret::plsda() do with
plsda() and MASS::lda() with lda(), and whichever package was attached last masks the other's. Write ecodive::pca() and so on, or use
count_ord(), which
always runs ecodive's, to be sure.
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.
See also
ca(), cca(), dpcoa(), lda(), oplsda(), pca(), plsda(), rda(), rpca(), rpca_phylo(), list_count_ords(); dist_ord() for
the methods that take distances.
Examples
ord <- count_ord(ex_counts, 'pca', norm = 'clr', pseudocount = 1)
head(ord)
#> PC1 PC2 PC3
#> Saliva -3.528246 -1.336813 0.879437784
#> Gums -3.691532 -1.381718 -0.860746227
#> Nose 6.050248 -2.662859 -0.010805525
#> Stool 1.169530 5.381390 -0.007886032
str(ord)
#> 'ecodive_ord' num [1:4, 1:3] -3.53 -3.69 6.05 1.17 -1.34 ...
#> - attr(*, "dimnames")=List of 2
#> ..$ : chr [1:4] "Saliva" "Gums" "Nose" "Stool"
#> ..$ : chr [1:3] "PC1" "PC2" "PC3"
#> - attr(*, "method")= chr "pca"
#> - attr(*, "eig")= num [1:3] 21.35 13.249 0.505
#> - attr(*, "prop")= num [1:3] 0.6082 0.3774 0.0144
#> - attr(*, "trace")= num 35.1
#> - attr(*, "loadings")= num [1:6, 1:3] -0.4926 -0.0683 0.4635 -0.564 0.3082 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:6] "Streptococcus" "Bacteroides" "Corynebacterium" "Haemophilus" ...
#> .. ..$ : chr [1:3] "PC1" "PC2" "PC3"
#> - attr(*, "display")=List of 1
#> ..$ title: chr "Principal Component Analysis"
# The same arguments for every method (but lda, plsda and oplsda,
# which need groups, and rpca_phylo and dpcoa, which need a tree).
ids <- setdiff(list_count_ords('id'), c('dpcoa', 'lda', 'oplsda', 'plsda', 'rpca_phylo'))
lapply(ids, function (m) attr(count_ord(ex_counts, m, n_axes = 2), 'prop'))
#> [[1]]
#> [1] 0.4572664 0.4438732
#>
#> [[2]]
#> [1] 0.4572664 0.4438732
#>
#> [[3]]
#> [1] 0.5428410 0.3713532
#>
#> [[4]]
#> [1] 0.5428410 0.3713532
#>
#> [[5]]
#> [1] 0.5737685 0.4262315
#>
ord <- count_ord(ex_counts, 'rpca_phylo', tree = ex_tree, n_axes = 2)
ord <- count_ord(ex_counts, 'dpcoa', tree = ex_tree, n_axes = 2)
count_ord(ex_counts, 'plsda', c('a', 'a', 'b', 'b'), n_axes = 1)
#> # A matrix: 4 samples × 1 axis
#> # Partial Least Squares Discriminant Analysis
#> # % of variance: 53.9
#> PLSDA1
#> Saliva -1.34
#> Gums -1.48
#> Nose 2.1
#> Stool 0.718
#> # Attributes: method, eig, prop, trace, loadings, weights, y_loadings, vip,
#> # groups, centroids
