phyloseq (version 1.12.2)

ordinate: Perform an ordination on phyloseq data

Description

This function wraps several commonly-used ordination methods. The type of ordination depends upon the argument to method. Try ordinate("help") or ordinate("list") for the currently supported method options.

Usage

ordinate(physeq, method = "DCA", distance = "bray", formula = NULL, ...)

Arguments

physeq

(Required). Phylogenetic sequencing data (phyloseq-class). The data on which you want to perform the the ordination. In general, these methods will be based in some fashion on the abundance table ultimately stored as a contingency matrix (otu_table-class). If you're able to import data into phyloseq-class format, than you don't need to worry, as an otu_table is a required component of this class. In addition, some ordination methods require additional data, like a constraining variable or phylogenetic tree. If that is the case, the relevant data should be included in physeq prior to running. Integrating the data in this way also results in these different data components being checked for validity and completeness by the method.

method

(Optional). A character string. Default is "DCA".

Currently supported method options are: c("DCA", "CCA", "RDA", "CAP", "DPCoA", "NMDS", "MDS", "PCoA")

DCA

Performs detrended correspondence analysis usingdecorana

CCA

Performs correspondence analysis, or optionally, constrained correspondence analysis (a.k.a. canonical correspondence analysis), via cca

RDA

Performs redundancy analysis, or optionally principal components analysis, via rda

CAP

[Partial] Constrained Analysis of Principal Coordinates or distance-based RDA, via capscale. See capscale.phyloseq for more details. In particular, a formula argument must be provided.

DPCoA

Performs Double Principle Coordinate Analysis using a (corrected, if necessary) phylogenetic/patristic distance between species. The calculation is performed by DPCoA(), which ultimately uses dpcoa after making the appropriate accessions/corrections of the data.

NMDS

Performs Non-metric MultiDimenstional Scaling of a sample-wise ecological distance matrix onto a user-specified number of axes, k. By default, k=2, but this can be modified as a supplementary argument. This method is ultimately carried out by metaMDS after the appropriate accessions and distance calculations. Because metaMDS includes its own distance calculation wrappers to vegdist, and these provide additional functionality in the form of species scores, ordinate will pass-on the distance argument to metaMDS if it is among the supported vegdist methods. However, all distance methods supported by distance are supported here, including "unifrac" (the default) and "DPCoA".

MDS/PCoA

Performs principal coordinate analysis (also called principle coordinate decomposition, multidimensional scaling (MDS), or classical scaling) of a distance matrix (Gower 1966), including two correction methods for negative eigenvalues. See pcoa for further details.

distance

(Optional). A character string. Default is "bray". The name of a supported distance method; or, alternatively, a pre-computed dist-class object. This argument is only utilized if a distance matrix is required by the ordination method specified by the method argument (above).

Any supported distance methods are supported arguments to distance here. Try distance("list") for a explicitly supported distance method abbreviations. User-specified custom distance equations should also work, e.g. "(A+B-2*J)/(A+B)". See distance for more details, examples.

formula

(Optional). A model formula. Only relevant for certain ordination methods. The left hand side is ignored, defined by the physeq and distance arguemnts. The right hand side gives the constraining variables, and conditioning variables can be given within a special function Condition. See cca or capscale for examples/details.

...

(Optional). Additional arguments to supporting functions. For example, the additional argument weighted=TRUE would be passed on to UniFrac if "unifrac" were chosen as the distance option and "MDS" as the ordination method option. Alternatively, if "DCA" were chosen as the ordination method option, additional arguments would be passed on to the relevant ordination function, decorana, for example.

Value

An ordination object. The specific class of the returned object depends upon the ordination method, as well as the function/package that is called internally to perform it. As a general rule, any of the ordination classes returned by this function will be recognized by downstream tools in the phyloseq package, for example the ordination plotting function, plot_ordination.

See Also

The plot_ordination Tutorial

Related component ordination functions described within phyloseq:

DPCoA

Described/provided by other packages:

cca/rda, decorana, metaMDS, pcoa, capscale

NMDS and MDS/PCoA both operate on distance matrices, typically based on some pairwise comparison of the microbiomes in an experiment/project. There are a number of common methods to use to calculate these pairwise distances, and the most convenient function (from a phyloseq point of view) for calculating these distance matrices is the

distance

function. It can be thought of as a distance / dissimilarity-index companion function for ordinate, and indeed the distance options provided to ordinate are often simply passed on to distance.

A good quick summary of ordination is provided in the introductory vignette for vegan:

vegan introductory vignette

The following R task views are also useful for understanding the available tools in R:

Analysis of Ecological and Environmental Data

Multivariate Statistics

Examples

# See http://joey711.github.io/phyloseq/plot_ordination-examples
# for many more examples.
# plot_ordination(GP, ordinate(GP, "DCA"), "samples", color="SampleType")