pca.plot {SoundShape}

Plot ordination of Principal Components with convex hulls

Description

Ordination of Principal Components from the output of a Principal Components Analysis performed by prcomp function (stats package). Require a factor object with groups, which enable the plot to feature colored groups and convex hulls (if desired).

Usage

pca.plot(
  PCA.out = NULL,
  groups = NULL,
  col.gp = grDevices::rainbow(length(levels(groups))),
  conv.hulls = NULL,
  col.conv = grDevices::rainbow(length(levels(conv.hulls))),
  PCs = c(1, 2),
  main = "Ordination of PCA coordinates",
  sp.as = "points",
  sp.text = NULL,
  cross.origin = TRUE,
  lwd = 1,
  lty = "dotted",
  leg = TRUE,
  leg.labels = groups,
  leg.pos = "topright",
  cex.leg = 1,
  cex = 1,
  cex.axis = 1,
  cex.lab = 1,
  cex.main = 1
)

Arguments

PCA.out

the output of a Principal Components Analysis performed by prcomp (stats package). By default: PCA.out = NULL (i.e. output must be specified before ploting)

groups

groups to use as colors and/or convex hulls. Must be a factor object with the same length as the number of rows in the coordinates of PCA.out (i.e. length(groups) == nrow(PCA.out$x)). By default: groups = NULL (i.e. factor must be specified before ploting)

col.gp

a factor object with the colours intended for groups. Must be the same length as the number of levels from groups (i.e. length(col.gp) == length(levels(groups))). By default: col.gp = grDevices::rainbow(length(levels(groups))) (i.e. colors defined automatically)

conv.hulls

groups to use for convex hulls. Must be a factor object with the same length as the number of rows in the coordinates of PCA.out (i.e. length(conv.hulls) == nrow(PCA.out$x)). By default: conv.hulls = NULL (i.e. plot without convex hulls)

col.conv

a factor object with the colours intended for conv.hulls. Must be the same length as the number of levels in conv.hulls (i.e. length(col.conv) == length(levels(conv.hulls))). By default: col.conv = grDevices::rainbow(length(levels(conv.hulls))) (i.e. colors defined automatically)

PCs

a vector of length two with the Principal Components intended for the plot. By default: PCs = c(1, 2)

main

main title of output plot. Should be presented between quotation marks. By default: main = "Ordination of PCA coordinates"

sp.as

enables one to choose between ploting elements as "points" or "text". If sp.as = "text", also input a factor of characters to use as text (i.e. sp.text). By default: sp.as = "points"

sp.text

only applies when sp.as = "text". A factor including elements as texts intended in the plot. Has to be the same length as the number of rows in the coordinates of PCA.out (i.e. length(sp.text) == nrow(PCA.out$x)) . By default: sp.text = NULL

cross.origin

A logical. If TRUE, the ordination plot will include lines crossing at the origin (i.e. x = 0, y = 0). By default: cross.origin = TRUE

lwd

only applies when cross.origin = TRUE. The width for lines crossing at the origin. Same as in par. By default: lwd = 1

lty

only applies when cross.origin = TRUE. The type of lines crossing at the origin. Same as in par: "Line types can either be specified as an integer (0=blank, 1=solid (default), 2=dashed, 3=dotted, 4=dotdash, 5=longdash, 6=twodash) or as one of the character strings "blank", "solid", "dashed", "dotted", "dotdash", "longdash", or "twodash", where "blank" uses ‘invisible lines’ (i.e., does not draw them)." By default: lty = "dotted"

leg

a logical. If TRUE, a legend is added to plot. By default: leg = TRUE

leg.labels

only applies when leg = TRUE. Must be the same length of levels in groups (i.e. length(leg.labels) == length(levels(groups))). By default: leg.labels = groups (i.e. labels will be the same as the levels from groups)

leg.pos

only applies when leg = TRUE. Specify legend location in the plot by using a keyword from the list: "bottomright", "bottom", "bottomleft", "left", "topleft", "top", "topright", "right" and "center". Alternatively, a single value can be provided and used for both margins, or two values, in which the first is used for X distance, and the second for Y distance. See also legend for details. By default: leg.pos = "topright"

cex.leg

only applies when leg = TRUE. The magnification to be used in the legend. By default: cex.leg = 1

cex

same as in par: "A numerical value giving the amount by which plotting text and symbols should be magnified relative to the default". By default: cex = 1

cex.axis

same as in par. Relative to cex. The magnification to be used for axis annotation. By default: cex.axix = 1

cex.lab

same as in par. Relative to cex. The magnification to be used for x and y labels. By default: cex.lab = 1

cex.main

same as in par. Relative to cex. The magnification to be used for main title. By default: cex.main = 1

Value

Require the output of prcomp and a vector with groups to plot. In addition, it is also possible to include convex hulls around each group (i.e. conv.hulls) and to control the colors intended for each group (i.e. col.gp) and for each convex hull (i.e. col.conv).

Author(s)

Pedro Rocha

References

Rocha, P. & Romano, P. (2021) The shape of sound: A new R package that crosses the bridge between Bioacoustics and Geometric Morphometrics. Methods in Ecology and Evolution, 12(6), 1115-1121.

See Also

prcomp, palette, rgb, rainbow, legend

Useful links:

• https://github.com/p-rocha/SoundShape

• Report bugs at https://github.com/p-rocha/SoundShape/issues

Examples

data(eig.sample)

# PCA using 3D semilandmark coordinates
pca.eig.sample <- stats::prcomp(geomorph::two.d.array(eig.sample))

# Verify names for each acoustic unit and the order in which they appear
dimnames(eig.sample)[[3]]

# Create factor to use as groups in subsequent ordination plot
sample.gr <- factor(c(rep("centralis", 3), rep("cuvieri", 3), rep("kroyeri", 3)))

# Clear current R plot to prevent errors
grDevices::dev.off()

# Plot result of Principal Components Analysis
pca.plot(PCA.out = pca.eig.sample, groups = sample.gr, conv.hulls = sample.gr,
         main="PCA of 3D coordinates", leg=TRUE, leg.pos = "top")