vegan: ordipointlabel – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

ordipointlabel

Ordination Plots with Points and Optimized Locations for Text

Description

The function ordipointlabel produces ordination plots with points and text label to the points. The points are in the exact location given by the ordination, but the function tries to optimize the location of the text labels to minimize overplotting text. The function may be 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.8, 0.8), add = FALSE, select, ...)

## S3 method for class 'ordipointlabel'
plot(x, ...)

Arguments

`x`	For `ordipointlabel()` a result object from an ordination function. For `plot.ordipointlabel` an object resulting from a call to `ordipointlabel()`.
`display`	Scores displayed in the plot.
`choices`	Axes shown.
`col, pch, font, cex`	Colours, point types, font style and character expansion for each kind of scores displayed in the plot. These should be vectors of the same length as the number of items in `display`.
`add`	Add to an existing plot.
`select`	Items to be displayed. This can either be a logical vector which is `TRUE` for displayed items or a vector of indices of displayed items. `select` is only used if a single set of scores is being plotted (i.e. `length(display) == 1`), otherwise it is ignored and a warning issued. If a logical vector is used, it must have the same length as the scores plotted.
`...`	Other arguments passed to `points` and `text`.

Details

The function uses simulated annealing (optim, method = "SANN") to optimize the location of the text labels to the points. There are eight possible locations: up, down, sides and corners. There is a weak preference to text right above the point, and a weak avoidance of corner positions. The exact locations and the goodness of solution varies between runs, and there is no guarantee of finding the global optimum. 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 is modelled after pointLabel in maptools package (which has chained dependencies of S4 packages).

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 variable cex it is the smallest alternative.

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

The result object from ordipointlabel inherits from orditkplot, and can also be replotted with its plot method. 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.

Note

The function is designed for ordination graphics, and the optimization works properly with plots of isometric aspect ratio.

Author(s)

Jari Oksanen

References

See pointLabel for references.

Examples

data(dune)
ord <- cca(dune)
plt <- ordipointlabel(ord)

## set scaling - should be no warnings!
ordipointlabel(ord, scaling = "sites")

## plot then add
plot(ord, scaling = "symmetric", type = "n")
ordipointlabel(ord, display = "species", scaling = "symm", add = TRUE)
ordipointlabel(ord, display = "sites", scaling = "symm", add = TRUE)

## redraw plot without rerunning SANN optimisation
plot(plt)

vegan

Community Ecology Package

v2.5-7

GPL-2

Authors

Jari Oksanen, F. Guillaume Blanchet, Michael Friendly, Roeland Kindt, Pierre Legendre, Dan McGlinn, Peter R. Minchin, R. B. O'Hara, Gavin L. Simpson, Peter Solymos, M. Henry H. Stevens, Eduard Szoecs, Helene Wagner

Initial release