orditkplot {vegan}

Ordination Plot with Movable Labels

Description

Function orditkplot produces an editable ordination plot with points and labels. The labels can be moved with mouse, and the edited plot can be saved as an encapsulated postscript file or exported via R plot function to other graphical formats, or saved in the R session for further processing.

Usage

orditkplot(x, display = "species", choices = 1:2, width, xlim, ylim, 
   tcex = 0.8, tcol, pch = 1,  pcol, pbg, pcex = 0.7, labels,  ...)
## S3 method for class 'orditkplot'
plot(x, ...)
## S3 method for class 'orditkplot'
points(x, pch = x$args$pch, cex = x$args$pcex,
       col = x$args$pcol, bg = x$args$pbg, ...)
## S3 method for class 'orditkplot'
text(x, cex = x$args$tcex, col = x$args$tcol,
     font = attr(x$labels, "font"), ...)
## S3 method for class 'orditkplot'
scores(x, display, ...)

Arguments

x

An ordination result or any other object that scores can handle, or for the plot function the object dumped from the interactive orditkplot session.

display

Type of scores displayed. For ordination scores this typically is either "species" or "sites", and for orditkplot result it is either "points" or "labels".

choices

Axes displayed.

width

Width of the plot in inches; defaults to the current width of the graphical device.

xlim, ylim

x and y limits for plots: points outside these limits will be completely removed.

tcex

Character expansion for text labels.

tcol

Colour of text labels.

pch, pcol, pbg

Point type and outline and fill colours. Defaults pcol="black" and pbg="transparent". Argument pbg has an effect only in filled plotting characters pch = 21 to 25.

pcex

Expansion factor for point size.

labels

Labels used instead of row names.

cex, col, bg, font

graphical parameters used in the points and text methods. See par.

...

Other arguments passed to the function. These can be graphical parameters (see par) used in the plot, or extra arguments to scores. These arguments are ignored in plot, but honoured in text and points.

Details

Function orditkplot uses tcltk package to draw Tcl/Tk based ordination graphics with points and labels. The function opens an editable canvas with fixed points, but the labels can be dragged with mouse to better positions or edited. In addition, it is possible to zoom to a part of the graph.

The function knows the following mouse operations:

• Left mouse button can be used to move labels to better positions. A line will connect a label to the corresponding point.

• Double clicking left mouse button opens a window where the label can be edited. After editing the label, hit the Return key.

• Right mouse button (or alternatively, Shift-Mouse button with one-button mouse) can be used for zooming to a part of the graph. Keeping the mouse button down and dragging will draw a box of the zoomed area, and after releasing the button, a new plot window will be created (this is still preliminary: all arguments are not passed to the new plot).

In addition there are buttons for the following tasks: Copy to EPS copies the current plot to an encapsulated postscript (eps) file using standard Tcl/Tk utilities. The faithfulness of this copy is system dependent. Button Export plot uses plot.orditkplot function to redraw the plot into graphical file formats. Depending on the system, the following graphical formats may be available: eps, pdf, svg, png, jpeg, tiff, bmp or xfig. Some of the output formats may be edited with external software: svg files with Illustrator or Inkscape, and xfig with the legacy program XFig. Button Save to R writes the edited coordinates of labels and points to the R session for further processing, and the plot.orditkplot function can be used to display the results. For faithful replication of the plot, the graph must have similar dimensions as the orditkplot canvas had originally. The plot function cannot be configured, but it uses the same settings as the original Tcl/Tk plot. However, points and text functions are fully configurable, but use the stored defaults for consistency with plot.orditkplot if none are supplied. Finally, button Close closes the window.

The produced plot will have equal aspect ratio. The width of the horizontal axis is fixed, but vertical axes will be scaled to needed height, and you can use scrollbar to move vertically if the whole canvas does not fit the window. If you use dumped labels in ordinary R plots, your plot must have the same dimensions as the orditkplot canvas to have identical location of the labels.

The function only displays one set of scores. However, you can use ordipointlabel to produce a result object that has different points and text types for several sets of scores and this can be further edited with orditkplot. For a good starting solution you need to scale the ordipointlabel result so that the points span over the whole horizontal axis. The function cannot show environmental variables or constraints, but it is limited to unconstrained ordination.

The plot is a Tcl/Tk canvas, but the function tries to replicate standard graphical device of the platform, and it honours several graphical parameters (see par). Many of the graphical parameters can be given on the command line, and they will be passed to the function without influencing other graphical devices in R. At the moment, the following graphical parameters are honoured: pch bg, cex, cex.axis, cex.lab, col (for labels), col.axis, col.lab, family (for font faces), fg, font, font.axis, font.lab, lheight, lwd (for the box), mar, mex, mgp, ps, tcl. These can be set with par, and they also will influence other plots similarly.

The tkcanvas text cannot be rotated, and therefore vertical axis is not labelled, and las parameter will not be honoured in the Tcl/Tk plot, but it will be honoured in the exported R plots and in plot.orditkplot.

Value

Function returns nothing useful directly, but you can save the edited graph to a file or save the edited positions to an R session for further processing and plotting.

Note

You need tcltk package and R must have been configured with capabilities for tcltk. Depending on your OS, you may need to start X11 and set the display before loading tcltk and starting the function (for instance, with Sys.setenv("DISPLAY"=":0")). See tcltk-package.

Author(s)

Jari Oksanen

See Also

Function ordipointlabel is an automatic procedure with similar goals of avoiding overplotting, and its output can be edited with orditkplot. See ordiplot, plot.cca, and orditorp for alternative ordination plots, and scores for extracting ordination scores.

Examples

## The example needs user interaction and is not executed directly.
## It should work when pasted to the window.
## Not run: 
data(varespec)
ord <- cca(varespec)
## Do something with the graph and end by clicking "Dismiss"
orditkplot(ord, mar = c(4,4,1,1)+.1, font=3)
## Use ordipointlabel to produce a plot that has both species and site
## scores in different colors and plotting symbols
pl <- ordipointlabel(ord)
orditkplot(pl)

## End(Not run)