RAM (version 1.2.1.3)

pcoa.plot: Create a PCoA plot for an OTU Table

Description

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

Usage

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)

Arguments

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?

Value

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

Details

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.

See Also

vegdist

Examples

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)