Skip to contents

Supervised ordination of samples from a few features: Fisher's linear discriminants, the axes along which known groups are furthest apart relative to the variation within them. Gives the same scores, coefficients and proportion of trace as MASS::lda(), and, up to a constant factor, the same scores as scikit-learn's LinearDiscriminantAnalysis.

Usage

lda(
  counts,
  groups,
  data = NULL,
  margin = 1L,
  norm = "none",
  pseudocount = NULL,
  prior = NULL,
  n_axes = NULL,
  cpus = n_cpus()
)

Arguments

counts

A numeric matrix of feature values (samples \(\times\) features), or any of the table types listed under "Input Types". It needs more samples than features: at least the number of features plus the number of groups (see "Singular tables").

groups

The known group of each sample: a vector or factor with one value per sample, matched to the samples in counts by name when both are named, else in the same order. Or, when data is given, the name of one of its columns (or a vector with one value per row of data). Every distinct value is a group, numbers included; there must be at least two. A factor's unused levels are dropped.

data

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

margin

The margin containing samples. 1 if samples are rows, 2 if samples are columns. Ignored when counts is a special object class (e.g. phyloseq). Default: 1

norm

Normalize the incoming counts. Options are:

  • 'none': No transformation.

  • 'percent': Relative abundance (sample abundances sum to 1).

  • 'hellinger': Square root of relative abundance (the Hellinger transformation).

  • 'binary': Unweighted presence/absence (each count is either 0 or 1).

  • 'clr': Centered log ratio.

  • 'rclr': Robust centered log ratio.

  • 'log': Log relative abundance (log-TSS), with pseudocount added 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.

prior

The prior probability of each group: a numeric vector with one positive value per group, named by group or else in the order of the groups (a factor's levels, otherwise sorted), adding up to 1. It weights each group's mean in the centre of the scores and in the between-group variance, as in MASS::lda(). Default: NULL, the proportion of samples in each group.

n_axes

The number of discriminant axes to return. Default: NULL, which means as many as there are, up to 3. There are at most \(g - 1\) for \(g\) groups, and no more than the number of features; a larger n_axes is reduced to that.

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 discriminant axis, named "LD1", "LD2", etc., as described in "Ordination result" below. The values are the discriminant scores, as predict(MASS::lda(...))$x gives them. Attributes:

  • method: "lda".

  • eig: The ratio of the between-group to the within-group variance (mean squares) of the scores on each axis: MASS::lda()'s svd, squared (the "canonical F statistics").

  • prop: Each axis's proportion of the sum of eig over all the discriminant axes: MASS::lda()'s "proportion of trace", and scikit-learn's explained_variance_ratio_.

  • scaling: The coefficients of the discriminants: one row per feature and one column per axis (MASS::lda()'s scaling). The scores are the table, minus prior %*% means, times scaling.

  • means: The mean of each feature in each group: one row per group and one column per feature.

  • prior: The prior probabilities, named by group.

  • groups: Each sample's group, as a factor whose levels are the groups, in the order of the rows of means.

Details

Method

Let \(X\) be the normalized table, \(m_k\) the mean of group \(k\) (of \(n_k\) samples, with prior \(\pi_k\)), and \(\bar{x} = \sum_k \pi_k m_k\). With \(W\) the pooled within-group covariance (each sample minus its group's mean, divisor \(n - g\)) and \(B\) the between-group covariance \(\sum_k n \pi_k (m_k - \bar{x})(m_k - \bar{x})^T / (g - 1)\) (with the default priors, \(n \pi_k = n_k\)), the discriminant axes \(a\) maximize \(a^T B a / a^T W a\), the ratio of the between-group to the within-group variance of the scores (Fisher 1936). They are the eigenvectors of \(W^{-1} B\), and the ratios its eigenvalues, eig. Each axis is scaled so that the pooled within-group variance of its scores is 1, and the scores are \((x - \bar{x})^T a\), for every sample \(x\).

As in scikit-learn's "svd" solver, \(W\) and \(B\) are never formed: the axes come from the SVD of the within-group residuals (each feature scaled by its within-group standard deviation), which spheres \(W\), then the SVD of the weighted group means in that sphered space. Axes whose singular value is below \(10^{-4}\) times the first are dropped, as both references do.

Singular tables

LDA needs \(W\) to be invertible: more samples than features plus groups, and no feature that is constant within every group or a linear combination of others within groups (as relative abundances that add up to 1 are). Otherwise lda() stops with an error (scikit-learn and MASS::lda() drop the null directions with a warning, but the axes they then report depend on rounding). Microbiome tables have far more taxa than samples, so use capda() instead: canonical analysis of principal coordinates (Anderson & Willis 2003) runs LDA on the first few axes of pcoa(), choosing how many by how well they classify the samples, and tests the separation of the groups by permutation. capda(dm, groups, n_pcoa_axes = 5) gives the same scores as lda(pcoa(dm, n_axes = 5), groups). A few axes of pca() also work.

Validate the separation

LDA is supervised: it looks for the directions that separate the groups, so its plots separate them, if not as readily as plsda()'s, even when the groups don't differ. Don't read the plot as evidence of a difference. Test it with a permutation test of the distances, such as permanova(), or estimate the error rate of classifying new samples by cross-validation.

Matching MASS and scikit-learn

lda() gives the same scores, scaling, group means and proportion of trace as MASS::lda() and its predict(), up to the sign of each axis, and eig is the square of its svd. scikit-learn's LinearDiscriminantAnalysis(solver = "svd") divides the within-group covariance by \(n\) rather than \(n - g\), so its transform() scores and scalings_ are larger by \(\sqrt{n / (n - g)}\); its explained_variance_ratio_ is prop. Its priors that don't add up to 1 are rescaled with a warning; here they are an error.

Same names in other packages

MASS::lda() shares its name with ecodive's lda(), and MASS is often attached: whichever package was attached last masks the other's. Write ecodive::lda(), or use count_ord(), which always runs ecodive's, to be sure. Elsewhere, "LDA" also means latent Dirichlet allocation (topic models), and LEfSe's "LDA score" is an effect size from this method.

Axis signs and reproducibility

An axis's sign is arbitrary, so different software can return mirror images of the same axis. lda() flips each axis so that its largest score in absolute value is positive, and flips its column of scaling with it. 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.

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

  • phyloseq

  • rbiom

  • SummarizedExperiment

  • TreeSummarizedExperiment

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

Fisher, R. A. (1936). The use of multiple measurements in taxonomic problems. Annals of Eugenics, 7(2), 179-188. doi:10.1111/j.1469-1809.1936.tb02137.x

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

Venables, W. N., & Ripley, B. D. (2002). Modern Applied Statistics with S (4th ed.). Springer. doi:10.1007/978-0-387-21706-2

Pedregosa, F., et al. (2011). Scikit-learn: machine learning in Python. Journal of Machine Learning Research, 12, 2825-2830.

Examples

    # LDA of iris: three groups, so two discriminant axes.
    ord <- lda(iris[, 1:4], 'Species', iris)
    plot(ord)

    attr(ord, 'prop')
#> [1] 0.991212605 0.008787395
    attr(ord, 'scaling')
#>                     LD1         LD2
#> Sepal.Length  0.8293776  0.02410215
#> Sepal.Width   1.5344731  2.16452123
#> Petal.Length -2.2012117 -0.93192121
#> Petal.Width  -2.8104603  2.83918785

    # Microbiome tables have more taxa than samples: use a few PCoA axes,
    # or capda(), which chooses how many.
    grp <- rep(c('a', 'b'), length.out = nrow(ex_counts))
    pc  <- pcoa(bray(ex_counts), n_axes = 2)
    lda(pc, grp)
#> # A matrix: 4 samples × 1 axis
#> # Linear Discriminant Analysis
#> # % of variance: 100.0
#>            LD1
#> Saliva  0.0178
#> Gums   -0.033
#> Nose    1.45
#> Stool  -1.43
#> # Attributes: method, eig, prop, scaling, means, prior, groups

    # Supervised: always validate the separation, e.g. with PERMANOVA.
    permanova(bray(ex_counts), grp, permutations = 99)
#> Permutational multivariate analysis of variance (PERMANOVA) of Bray-Curtis Dissimilarity
#> 
#> F = 0.7124, p = 0.68, z = -0.6451
#> Permutations: 99 (free)
#> 
#> Model R2 = 0.2626. Model tested as a whole:
#> 
#>          Df SumOfSqs     R2     F Pr(>F)
#> Model     1   0.3390 0.2626 0.712   0.68
#> Residual  2   0.9517 0.7374             
#> Total     3   1.2907 1.0000