Skip to contents

Constrained ordination of samples from their distances, like dbrda(), but of the principal coordinates with positive eigenvalues only. Gives the same results as vegan::capscale() (and so as phyloseq::ordinate(method = "CAP")). For Euclidean distances it gives the same results as dbrda().

Usage

capscale(dm, groups, data = NULL, formula = NULL, n_axes = 3L, cpus = n_cpus())

Arguments

dm

A dist object, such as from beta_div() or bray(), or a symmetric numeric matrix of distances. Must not contain NAs or negative values. Alternatively, as in vegan::dbrda(), a formula with the distances on its left-hand side and the constraints on its right, such as dm ~ treatment, in place of dm and formula; the metadata may then be given second, as in dbrda(dm ~ treatment, meta).

groups

The one variable that constrains the ordination: a vector or factor with one value per sample, matched to the samples in dm by name when both are named, else in the same order as dm. Or, when data is given, the name of one of its columns (or a vector with one value per row of data). Categories (factor, character, or logical) or a numeric covariate. The same as formula = ~ groups. Give groups or formula, not both.

data

Sample metadata: a data frame with one row per sample, holding the columns named in groups or formula. Rows are matched to the samples in dm by row name, and rows for other samples are ignored; without row names, they must be in the same order as dm. Default: NULL.

formula

Instead of groups, for models of several variables: a one-sided formula naming the variables in data that constrain the ordination, such as ~ treatment + ph. Factors, numeric covariates, and interactions are all allowed. Wrap variables in Condition() to remove their effect first (a partial analysis), as in vegan::dbrda(): ~ treatment + Condition(site). With only Condition() terms, the result is the unconstrained ordination after removing their effect. A left-hand side, if given, is ignored. Give groups or formula: there is no default model. Default: NULL.

n_axes

The number of axes to return. Default: 3. Reduced, with a warning, to the number of axes with positive eigenvalues, which is at most \(n - 1\) for \(n\) samples.

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 any cpus.

Value

A numeric matrix with one row per sample and one column per axis, as described in "Ordination result" below. Constrained axes come first, named "CAP1", "CAP2", etc., then, if the constraints give fewer than n_axes of them, unconstrained axes named "MDS1", "MDS2", etc. The values are vegan's site scores ("wa" scores, scaling 2), as for dbrda(). Its attributes are:

  • method: "capscale".

  • eig: The eigenvalue of each axis.

  • prop: The proportion of the real inertia (see inertia) that each axis explains, not counting the conditional inertia: eig / (trace - inertia[["imaginary"]] - inertia[["conditional"]]). vegan's "Proportion Explained".

  • trace: The total inertia, vegan's: the sum of all eigenvalues of \(G\), including negative ones, as dbrda()'s.

  • inertia: The total inertia split into four parts, which add up to trace: a named vector of

    • conditional: explained by the Condition() variables (0 if there are none);

    • constrained: explained by the constraints, after the conditions;

    • unconstrained: the rest of the real inertia;

    • imaginary: the sum of the negative eigenvalues of \(G\), which capscale() leaves out (0 for Euclidean distances).

    The first three add up to the real inertia, trace - imaginary, the sum of the positive eigenvalues of \(G\).

  • constrained_eig: Every non-zero constrained eigenvalue.

  • r_squared: The proportion of the real inertia that the constraints explain, inertia[["constrained"]] / (trace - inertia[["imaginary"]]), as vegan::RsquareAdj(x)$r.squared.

  • adj_r_squared: r_squared adjusted for the number of constraint columns, as vegan::RsquareAdj(x)$adj.r.squared and as for dbrda(). With conditions, vegan takes their proportion of trace, not of the real inertia, and so does capscale().

  • biplot, centroids: As for dbrda().

Details

Method

With \(G = -\frac{1}{2}JAJ\) as in pcoa() and dbrda(), and its eigen-decomposition \(G = V\Lambda V^T\), the principal coordinates with positive eigenvalues are \(Y = V_+\Lambda_+^{1/2}\), and \(G_+ = YY^T\) is the positive part of \(G\). capscale() is the redundancy analysis of \(Y\) on the constraints, which is dbrda() with \(G_+\) in place of \(G\). As in vegan, eigenvalues within max(e, e * lambda1) of 0, for \(e\) = sqrt(.Machine$double.eps) and \(\lambda_1\) the largest, count as 0.

For Euclidean distances (such as Euclidean, Hellinger, or Aitchison distances), \(G\) has no negative eigenvalues, so \(G_+ = G\). capscale() first looks for a negative eigenvalue, by block Lanczos iteration on \(-G\) with products straight from dm (as pcoa() finds the largest eigenvalues). It stops as soon as one is certain, and otherwise runs until the smallest eigenvalue of \(G\) has converged. Having found none, the rest is exactly dbrda()'s, in as little memory. That is quick when \(G\) has many eigenvalues at 0, such as for Euclidean distances between samples with fewer features than samples. When the smallest eigenvalues are close together, convergence can take many steps; after about \(n/10\) of them (each one pass over dm), when going on would cost about as much as the full eigen-decomposition, capscale() stops looking and decomposes \(G\), as below, which gives the same results either way.

Otherwise, \(G_+\) needs every eigenvalue of \(G\), as in vegan::capscale(): capscale() forms \(G\) (\(8n^2\) bytes, such as 200 MB for 5000 samples), reduces it to tridiagonal form, finds all of its eigenvalues, and then the eigenvectors of the positive ones, or of the others if they are fewer, by inverse iteration. That takes time proportional to \(n^3\), though several times less than a full eigen-decomposition: for 2000 Bray-Curtis distances, about 2 seconds on one core, against 12 for vegan::capscale(). The reduction and the eigenvectors are computed in parallel on cpus threads.

capscale() or dbrda()?

See dbrda(). In short: dbrda() analyzes the distances as they are, and quickly for any number of samples; capscale() analyzes the closest Euclidean configuration, so its eigenvalues are never negative, but it ignores the rest and takes much longer for large non-Euclidean data. Another way to avoid negative eigenvalues is to make the distances Euclidean first, such as by the square roots of Bray-Curtis distances (Legendre & Legendre 2012, Table 7.2), or with pcoa()'s correction, and then to use dbrda().

Matching vegan

capscale() gives the same scores, eigenvalues, inertia (including the imaginary inertia), \(R^2\), biplot scores and centroids as vegan::capscale() given distances, up to the signs of the axes. As there, distances are divided by \(\sqrt{n-1}\) when any is 4 or more (see "Scale" in dbrda()). vegan::capscale() can also take a community table, add a constant to the distances (add), or take their square roots (sqrt.dist), and gives species scores; capscale() does not.

capscale() is named after vegan::capscale(). Anderson & Willis's (2003) "canonical analysis of principal coordinates" (CAP) is a related but different method.

Axis signs and reproducibility

As for dbrda(): each axis's largest score in absolute value is positive, and results are identical from run to run and for any number of cpus.

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.

References

Legendre, P., & Anderson, M. J. (1999). Distance-based redundancy analysis: testing multispecies responses in multifactorial ecological experiments. Ecological Monographs, 69(1), 1-24. doi:10.1890/0012-9615(1999)069[0001:DBRATM]2.0.CO;2

Anderson, M. J., & Willis, T. J. (2003). Canonical analysis of principal coordinates: a useful method of constrained ordination for ecology. Ecology, 84(2), 511-525. doi:10.1890/0012-9658(2003)084[0511:CAOPCA]2.0.CO;2

Legendre, P., & Legendre, L. (2012). Numerical Ecology (3rd English ed.). Elsevier.

Examples

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

    ord
#> # A matrix: 150 samples × 3 axes
#> # Constrained Analysis of Principal Coordinates of Bray-Curtis Dissimilarity
#> # % of variance: 76.7, 3.0, 8.4
#>     CAP1    CAP2     MDS1
#>  1 0.507 -0.263  -0.074
#>  2 0.505  0.265   0.311
#>  3 0.557 -0.0882  0.214
#>  4 0.535  0.0909  0.281
#>  5 0.528 -0.337  -0.059
#>  6 0.411 -0.267  -0.401
#>  7 0.555 -0.275   0.101
#>  8 0.499 -0.166  -0.00641
#>  9 0.572  0.411   0.57
#> 10 0.507  0.137   0.218
#> # … 140 more samples
#> # Use print(x, n = ...) to see more samples
#> # Attributes: method, eig, prop, trace, inertia, constrained_eig, r_squared,
#> #   adj_r_squared, biplot, centroids
    str(ord)
#>  'ecodive_ord' num [1:150, 1:3] 0.507 0.505 0.557 0.535 0.528 ...
#>  - attr(*, "dimnames")=List of 2
#>   ..$ : NULL
#>   ..$ : chr [1:3] "CAP1" "CAP2" "MDS1"
#>  - attr(*, "method")= chr "capscale"
#>  - attr(*, "eig")= num [1:3] 2.234 0.086 0.244
#>  - attr(*, "prop")= num [1:3] 0.7674 0.0296 0.084
#>  - attr(*, "trace")= num 2.64
#>  - attr(*, "inertia")= Named num [1:4] 0 2.32 0.591 -0.274
#>   ..- attr(*, "names")= chr [1:4] "conditional" "constrained" "unconstrained" "imaginary"
#>  - attr(*, "constrained_eig")= num [1:2] 2.234 0.086
#>  - attr(*, "r_squared")= num 0.797
#>  - attr(*, "adj_r_squared")= num 0.794
#>  - attr(*, "biplot")= num [1:2, 1:3] -0.275 -0.695 0.962 -0.719 0 ...
#>   ..- attr(*, "dimnames")=List of 2
#>   .. ..$ : chr [1:2] "Speciesversicolor" "Speciesvirginica"
#>   .. ..$ : chr [1:3] "CAP1" "CAP2" "MDS1"
#>  - attr(*, "centroids")= num [1:3, 1:3] 0.499 -0.141 -0.357 -0.125 0.494 ...
#>   ..- attr(*, "dimnames")=List of 2
#>   .. ..$ : chr [1:3] "Speciessetosa" "Speciesversicolor" "Speciesvirginica"
#>   .. ..$ : chr [1:3] "CAP1" "CAP2" "MDS1"
#>  - attr(*, "display")=List of 1
#>   ..$ title: chr "Constrained Analysis of Principal Coordinates of Bray-Curtis Dissimilarity"