ordipointlabel: Ordination Plots with Points and Optimized Locations for Text

Description

Function produces ordination plots with labelled points. The points are in the fixed locations given by the ordination, but the locations of the text labels are optimized to minimize overplotting. The function is useful with moderately crowded ordination plots.

Usage

ordipointlabel(x, display = c("sites", "species"), choices = c(1, 2),
   col = c(1, 2),  pch = c("o", "+"), font = c(1, 1), 
   cex = c(0.7, 0.7), add = inherits(x, "ordiplot"), labels, bg, select,
   points = TRUE, ...)
# S3 method for ordipointlabel
plot(x, ...)

Arguments

Value

The function returns invisibly an object of class

ordipointlabel with items xy for coordinates of points, labels for coordinates of labels, items pch,

cex and font for graphical parameters of each point or label. In addition, it returns the result of optim as an attribute "optim". The unit of overlap is the area of character "m", and with varying graphical parameters the smallest alternative.

There is a plot method based on orditkplot but it does not alter or reset the graphical parameters via par.

The result object from ordipointlabel is similar as the

orditkplot object of vegan3d package, and it may be possible to further edit the result object with

orditkplot, but for good results it is necessary that the points span the whole horizontal axis without empty margins.

Details

The function uses simulated annealing (optim, method = "SANN") to optimize the locations of the text labels to the points. There are eight possible locations: up, down, two sides and four corners. There is a weak preference to text away from zero, and a weak avoidance of corners. The locations and goodness of solution varies between runs, and there is no guarantee of finding the global optimum, or the same text locations twice. The optimization can take a long time in difficult cases with a high number of potential overlaps. Several sets of scores can be displayed in one plot.

The function can be used in a pipe where the first command is an ordination plot command with type = "n" or to add points and labels to save vegan ordination plot object. See examples.

Examples

Run this code

data(dune, dune.env)
ord <- cca(dune)
ordipointlabel(ord)

## Use in a pipe: optimize species, sites & centroids together
ord <- cca(dune ~ Management + Moisture, dune.env)
plot(ord, scaling = "symmetric", type = "n") |>
  ordipointlabel(c("sites","species","centroids"), cex=c(0.7,0.7,1),
      col = c("black","red","blue"), font = c(1,3,1), pch=c(1,3,4), xpd=TRUE) |>
  text("biplot", col = "blue", bg = "white", cex=1)