pcoa.plot: Create a PCoA plot for an OTU Table
In RAM: R for Amplicon-Sequencing-Based Microbial-Ecology

Description Usage Arguments Details Value Note Author(s) See Also Examples

This function consumes an OTU table, metadata factors, and graphing options, then produces a plot showing the PCoA analysis of the OTU table.

pcoa.plot(data, is.OTU=TRUE, meta, factors, rank, 
          stand.method = NULL, dist.method = "morisita", 
          sample.labels = TRUE, top = 20,
          ellipse = FALSE, main = NULL, file = NULL, ext = NULL,
          height = 8, width = 10, ggplot2 = TRUE, bw = FALSE)

`data`	an OTU table or taxonomic abundance matrix to be used.
`is.OTU`	logical. Whether or not the input data an OTU table.
`meta`	the metadata table to be used.
`factors`	a named character vector of length 1 or 2 specifying metadata factors for the samples in the OTU table (see Details).
`rank`	the rank to select the taxon groups at. For an OTU table, if `rank` is set `NULL`, distance matrix will be calcuated using all OTUs, otherwise, the OTU table will be transformed to taxonomic abundance matrix before the calculation of the distance matrix. If a taxonomic abundance matrix is provided, i.e. `is.OTU` is set `TRUE`, then the `rank` will be ignored.
`stand.method`	a method used to standardize the OTU table. One of "`total`", "`max`", "`freq`", "`normalize`", "`range`", "`standardize`", "`pa`", "`chi.square`", "`hellinger`" or "`log`" (see ?decostand).
`dist.method`	the dissimilarity index to be used; one of "`manhattan`", "`euclidean`", "`canberra`", "`bray`", "`kulczynski`", "`jaccard`", "`gower`", "`altGower`","`morisita`", "`horn`", "`mountford`", "`raup`", "`binomial`", "`chao`", or "`cao`" (see `vegdist`).
`sample.labels`	logical. Should the labels for the samples be displayed?
`top`	how many taxon groups should be displayed, starting from the most abundant.
`ellipse`	which of the metadata factors (if any) should have ellipses plotted around them. Must be one of 1, 2, or FALSE (see Details).
`main`	The title of the plot.
`file`	the file path where the image should be created (see ?RAM.plotting).
`ext`	the file type to be used; one of `"pdf"`, `"png"`, `"tiff"`, `"bmp"`, `"jpg"`, or `"svg"`.
`height`	the height of the image to be created (in inches).
`width`	the width of the image to be created (in inches).
`ggplot2`	logical. Should the `ggplot2` package be used to produce the plot, or should the base graphics be used? (see ?RAM.plotting).
`bw`	logical. Should the image be created in black and white?

This function uses pco in the labdsv package for the Principal coordinates analysis (PCoA). The distance matrix was square rooted before being passed to pco to avoid negative eigenvalues. factors should be a named character vector specifying the names of the columns to be used from meta (see RAM.factors). Those columns should be factors; if they are not, a warning is raised and they are coerced to factors (see factor). A warning is also raised when a factor has more than 9 levels, as that is the most colours the current palettes support.

The values on the axes denote what fraction of the sum of all eigenvalues (i.e. from all axes) is explained by that (single) axis. When ellipse = FALSE, no ellipses will be plotted. When ellipse is a number, that 'number' metadata factor will have ellipses plotted.

For example, if factors = c(Crop="Crop", City="City") and ellipse = 1, ellipses will be plotted for the different crops, but NOT the cities. Setting factors = c(City="City") and ellipse = 2 is invalid, since there is no second metadata factor given. Ellipses can only be plotted for one factor currently. Furthermore, there need to be at least 3 samples for every level in every item in factors, otherwise ellipses cannot be plotted.

When ggplot2 = TRUE, a ggplot object is returned; otherwise nothing ism returned (but the plot is shown on screen).

The labels for the sample points are placed above, below, or next to the point itself at random. If labels are outside of the plotting area, or overlapping with each other, run your command again (without changing any arguments!) and the labels should move to new positions. Repeat until they are placed appropriately. This is done to ensure even tightly-grouped samples, or samples near the edge of the plot, have their labels shown. If the labels are too distracting, remember that they can be turned off by setting sample.labels = FALSE.

Wen Chen and Joshua Simpson.

vegdist

data(ITS1, meta)
# The argument for factors is a vector of length two; the first
# item is # Crop, which is a column from meta, and the second 
# item is City, another # column from meta.
pcoa.plot(ITS1, meta=meta, rank="c",
          factors=c(Crop="Crop", City="City"))
## Not run: 
# If you want to customize legend labels and plot the top 20 
# taxon groups at genus:
pcoa.plot(ITS1, meta=meta, rank="g", main="PCoA plot",
          factors=c(Place="City", 
          Harvest_Method="Harvestmethod"))
# In black & white, using base graphics:
pcoa.plot(ITS1, meta=meta, rank="c", factors=c(Plot="Plots"),
          ggplot=F, bw=T)
pcoa.plot(ITS1, meta=meta, rank="c", factors=c(Plot="Plots"),
          ggplot=F, bw=T, dist.method="euc", 
          stand.method="hell")
# Focus on the samples: hide all groups and plot ellipses 
# for Crop:
pcoa.plot(ITS1, meta=meta, rank="g",
          factors=c(Crop="Crop", City="City"),
          ellipse=1, sample.labels=FALSE, top=0)
# Standardize the data before calculating distances:
pcoa.plot(ITS1, meta=meta, rank="g", factors=c(City="City"),
          stand.method="chi.square",
          dist.method="euclidean")

## End(Not run)

Loading required package: vegan
Loading required package: permute
Loading required package: lattice
This is vegan 2.4-4
Loading required package: ggplot2
sh: 1: cannot create /dev/null: Permission denied
sh: 1: cannot create /dev/null: Permission denied
Scale for 'shape' is already present. Adding another scale for 'shape', which
will replace the existing scale.
Warning: Ignoring unknown aesthetics: shape
Scale for 'colour' is already present. Adding another scale for 'colour',
which will replace the existing scale.
Warning message:
In .pcoa.ggplot2(abund, pcoa, rank, sp.scores, meta.factors, sample.labels,  :
  there are less than 20 taxon groups at the given rank; plotting them all.
Scale for 'shape' is already present. Adding another scale for 'shape', which
will replace the existing scale.
Warning: Ignoring unknown aesthetics: shape
Scale for 'colour' is already present. Adding another scale for 'colour',
which will replace the existing scale.
Warning message:
In .pcoa.base(abund, pcoa, rank, sp.scores, meta.factors, sample.labels,  :
  there are less than 20 taxon groups at the given rank; plotting them all.
Warning message:
In .pcoa.base(abund, pcoa, rank, sp.scores, meta.factors, sample.labels,  :
  there are less than 20 taxon groups at the given rank; plotting them all.
Scale for 'shape' is already present. Adding another scale for 'shape', which
will replace the existing scale.
Scale for 'colour' is already present. Adding another scale for 'colour',
which will replace the existing scale.
Warning message:
In pcoa.plot(ITS1, meta = meta, rank = "g", factors = c(Crop = "Crop",  :
  drawing the ellipses for groups is not currently supported when 'ggplot2=TRUE'.
Scale for 'shape' is already present. Adding another scale for 'shape', which
will replace the existing scale.
Warning: Ignoring unknown aesthetics: shape