Skip to contents

Runs any of ecodive's ordination methods that take a count table by name, as dist_ord() does for the methods that take distances.

Usage

count_ord(counts, method, ...)

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 via list_count_ords().

...

Further arguments for the method's function, such as n_axes, margin, cpus, pca()'s norm, pseudocount, and scale, or rda()'s and cca()'s groups, data, and formula, or lda()'s, plsda()'s and oplsda()'s groups and data, or rpca_phylo()'s tree, or dpcoa()'s tree or taxa_dm. Each method keeps its own defaults; see ca(), cca(), dpcoa(), lda(), oplsda(), pca(), plsda(), rda(), rpca(), and rpca_phylo(). seed is ignored by the methods that have no random parts (all but cca(), 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 NameMethod Name
caCorrespondence Analysis (CA)
ccaCanonical Correspondence Analysis (CCA), constrained
dpcoaDouble Principal Coordinate Analysis (DPCoA) (needs tree or taxa_dm)
ldaLinear Discriminant Analysis (LDA), supervised
oplsdaOrthogonal PLS Discriminant Analysis (OPLS-DA), supervised
pcaPrincipal Component Analysis (PCA)
plsdaPartial Least Squares Discriminant Analysis (PLS-DA), supervised
rdaRedundancy Analysis (RDA), constrained
rpcaRobust Aitchison PCA
rpca_phyloPhylogenetic 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() and isomap() give the eigenvalues of Gower's centered matrix (sums of squares); pca() and rpca() give variances, which are pcoa()'s divided by \(n - 1\) for \(n\) samples; and dbrda() and capscale() follow vegan, which also divides by \(n - 1\) when any distance is 4 or more. NA for mds(), nmds(), tsne(), and umap(), which have no eigenvalues.

  • prop: The proportion of the total variance (or inertia) that each axis explains. Unlike eig, it is comparable between methods, so use it to label axes. NA where 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

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