Skip to contents

Runs any of ecodive's distance-based ordination methods by name, as beta_div() does for beta diversity metrics and dist_test() does for statistical tests. Compute the distances once with beta_div() (or a metric's own function, such as bray()), then pass them to dist_ord() and dist_test().

Usage

dist_ord(dm, method, ...)

Arguments

dm

The distances to ordinate: a dist object such as from beta_div(), or a symmetric matrix of distances. Every method listed by list_dist_ords() takes distances.

method

The name of an ordination method: "capda", "capscale", "dbrda", "isomap", "mds", "nmds", "pcoa", "tsne", or "umap". Flexible matching is supported (see below). Programmatic access via list_dist_ords().

...

Further arguments for the method's function, such as n_axes, seed, cpus, or pcoa's correction. Each method keeps its own defaults; see capscale() and dbrda() (which also need groups, or data and formula, as in dist_ord(dm, 'dbrda', 'treatment', meta)), capda() (which needs groups, and data if groups names a column of it), isomap(), mds(), nmds(), pcoa(), tsne(), and umap(). seed is ignored by the methods that have no random parts (capscale, dbrda, isomap and pcoa), so the same arguments can be given to every method.

Value

The method's result, as described in "Ordination result" below. dist_ord(dm, 'pcoa', ...) is the same as pcoa(dm, ...).

Details

List of Ordination Methods

Option / Function NameMethod Name
capdaDiscriminant Canonical Analysis of Principal Coordinates (CAP), supervised
capscaleConstrained Analysis of Principal Coordinates
dbrdaDistance-based Redundancy Analysis (db-RDA)
isomapIsometric Feature Mapping (Isomap)
mdsMetric Multidimensional Scaling (MDS)
nmdsNon-metric Multidimensional Scaling (NMDS)
pcoaPrincipal Coordinates Analysis (PCoA)
tsnet-distributed Stochastic Neighbor Embedding (t-SNE)
umapUniform Manifold Approximation and Projection (UMAP)

pca(), rda(), cca(), ca() and rpca() ordinate a count table rather than distances, so they are run by count_ord(), or called directly. PCA is PCoA of Euclidean distances: dist_ord(euclidean(counts), 'pcoa') gives the same scores as pca(counts), up to each axis's sign, but pca() also returns the features' loadings and never forms the distance matrix. permanova() and ecodive's other tests are run by dist_test().

Default numbers of axes differ: n_axes = 3 for the methods whose axes have eigenvalues (capscale, dbrda, isomap, pcoa, and pca() and rpca(); capda returns up to 3, and at most one fewer than the number of groups), and n_axes = 2 for those that fit a layout in a fixed number of dimensions (mds, nmds, tsne, and umap).

Flexible name matching

Case insensitive and partial matching, ignoring anything but letters. E.g. method = 'PCoA' or 'principal coord' selects pcoa. Common other names also work: 'PCO', 'cmdscale', or 'classical MDS' for pcoa; 'MDS' or 'metric MDS' for mds; 'non-metric MDS', 'metaMDS', 'monoMDS', or 'isoMDS' for nmds; 'isometric mapping' for isomap; 'Rtsne', 'bhtsne', or 'Barnes-Hut t-SNE' for tsne; and 'uwot' for umap. 'dbRDA' or 'distance-based RDA' select dbrda, and 'CAP' selects capscale (but 'CA' names ca(), which takes a count table). 'CAPdiscrim' (BiodiversityR's name) or 'discriminant CAP' select capda, Anderson & Willis's discriminant CAP.

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

ape::pcoa(), vegan::pca(), vegan::dbrda(), vegan::capscale(), vegan::isomap() (whose k is the number of neighbours, not axes), and uwot::umap() share names with ecodive's functions, and whichever package was attached last masks the other's. Write ecodive::pcoa() and so on, or use dist_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

capda(), capscale(), dbrda(), isomap(), mds(), nmds(), pcoa(), tsne(), umap(), list_dist_ords(); count_ord() for pca(), rda(), cca(), ca() and rpca(), which take a count table; dist_test() for ecodive's tests.

Examples

    dm  <- bray(iris[, 1:4])
    ord <- dist_ord(dm, 'pcoa')
    plot(ord, 'Species', iris)

    ord
#> # A matrix: 150 samples × 3 axes
#> # Principal Coordinates Analysis of Bray-Curtis Dissimilarity
#> # % of variance: 89.0, 9.3, 2.9
#>    PCoA1   PCoA2    PCoA3
#>  1 0.169 -0.0259 -0.00505
#>  2 0.171  0.0235  0.0308
#>  3 0.187 -0.0032  0.0322
#>  4 0.18   0.0113  0.0372
#>  5 0.176 -0.03   -0.00613
#>  6 0.136 -0.0398 -0.0431
#>  7 0.186 -0.0182  0.0156
#>  8 0.167 -0.0165  0.00287
#>  9 0.194  0.0406  0.0413
#> 10 0.171  0.011   0.0286
#> # … 140 more samples
#> # Use print(x, n = ...) to see more samples
#> # Attributes: method, eig, prop, trace, correction, constant
    str(ord)
#>  'ecodive_ord' num [1:150, 1:3] 0.169 0.171 0.187 0.18 0.176 ...
#>  - attr(*, "dimnames")=List of 2
#>   ..$ : NULL
#>   ..$ : chr [1:3] "PCoA1" "PCoA2" "PCoA3"
#>  - attr(*, "method")= chr "pcoa"
#>  - attr(*, "eig")= num [1:3] 2.3473 0.2459 0.0766
#>  - attr(*, "prop")= num [1:3] 0.8901 0.0932 0.0291
#>  - attr(*, "trace")= num 2.64
#>  - attr(*, "correction")= chr "none"
#>  - attr(*, "constant")= num 0
#>  - attr(*, "display")=List of 1
#>   ..$ title: chr "Principal Coordinates Analysis of Bray-Curtis Dissimilarity"