pcoa_ord {supportR}

Publication-Quality Principal Coordinates Analysis (PCoA) Ordinations

Description

Produces Principal Coordinates Analysis (PCoA) ordinations for up to 10 groups. Assigns a unique color for each group and draws an ellipse around the standard deviation of the points. Automatically adds percent of variation explained by first two principal component axes parenthetically to axis labels. Because there are only five hollow shapes (see ?graphics::pch) all shapes are re-used a maximum of 2 times when more than 5 groups are supplied.

Usage

pcoa_ord(
  mod = NULL,
  groupcol = NULL,
  title = NA,
  colors = c("#41b6c4", "#c51b7d", "#7fbc41", "#d73027", "#4575b4", "#e08214", "#8073ac",
    "#f1b6da", "#b8e186", "#8c96c6"),
  shapes = rep(x = 21:25, times = 2),
  lines = rep(x = 1, times = 10),
  pt_size = 1.5,
  pt_alpha = 1,
  leg_pos = "bottomleft",
  leg_cont = unique(groupcol)
)

Arguments

mod

Object returned by ape::pcoa

groupcol

(dataframe) column specification in the data that includes the groups (accepts either bracket or $ notation)

title

(character) string to use as title for plot

colors

(character) vector of colors (as hexadecimal codes) of length >= group levels (default not colorblind safe because of need for 10 built-in unique colors)

shapes

(numeric) vector of shapes (as values accepted by pch) of length >= group levels

lines

(numeric) vector of line types (as integers) of length >= group levels

pt_size

(numeric) value for point size (controlled by character expansion i.e., cex)

pt_alpha

(numeric) value for transparency of points (ranges from 0 to 1)

leg_pos

(character or numeric) legend position, either numeric vector of x/y coordinates or shorthand accepted by graphics::legend

leg_cont

(character) vector of desired legend entries. Defaults to unique entries in groupcol argument (this argument provided in case syntax of legend contents should differ from data contents)

Value

(base R plot) base R plot with ellipses for each group

Examples

# Use data from the vegan package
data("varespec", package = 'vegan')
resp <- varespec

# Make some columns of known number of groups
factor_4lvl <- c(rep.int("Trt1", (nrow(resp)/4)),
                 rep.int("Trt2", (nrow(resp)/4)),
                 rep.int("Trt3", (nrow(resp)/4)),
                 rep.int("Trt4", (nrow(resp)/4)))

# And combine them into a single data object
data <- cbind(factor_4lvl, resp)

# Get a distance matrix from the data
dist <- vegan::vegdist(resp, method = 'kulczynski')

# Perform a PCoA on the distance matrix to get points for an ordination
pnts <- ape::pcoa(dist)

# Test the function for 4 groups
pcoa_ord(mod = pnts, groupcol = data$factor_4lvl)