ordiplot3d {vegan}R Documentation

Three-Dimensional and Dynamic Ordination Graphics

Description

Function ordiplot3d displays three-dimensional ordination graphics using scatterplot3d. Function ordirgl displays three-dimensional dynamic ordination graphs which can be rotated and zoomed into using rgl package. Both work with all ordination results form vegan and all ordination results known by scores function.

Usage

ordiplot3d(object, display = "sites", choices = 1:3, ax.col = 2,
        arr.len = 0.1, arr.col = 4, envfit, xlab, ylab, zlab, ...)
ordirgl(object, display = "sites", choices = 1:3, type = "p", 
        ax.col = "red", arr.col = "yellow", text, envfit, ...)
orglpoints(object, display = "sites", choices = 1:3, ...)
orgltext(object, text, display = "sites", choices = 1:3, justify = "center", 
        adj = 0.5, ...)
orglsegments(object, groups, display = "sites", choices = 1:3, ...)
orglspider(object, groups, display = "sites", w = weights(object, display),
        choices = 1:3, ...)

Arguments

object An ordination result or any object known by scores.
display Display "sites" or "species" or other ordination object recognized by scores.
choices Selected three axes.
arr.len 'Length' (width) of arrow head passed to arrows function.
arr.col Colour of biplot arrows and centroids of environmental variables.
type The type of plots: "p" for points or "t" for text labels.
ax.col Axis colour (concerns only the crossed axes through the origin).
text Text to override the default with type = "t".
envfit Fitted environmental variables from envfit displayed in the graph.
xlab, ylab, zlab Axis labels passed to scatterplot3d. If missing, labels are taken from the ordination result. Set to NA to suppress labels.
justify, adj Text justification passed to rgl.texts. One of these is used depending on the version of rgl installed.
groups Factor giving the groups for which the graphical item is drawn.
w Weights used to find the average within group. Weights are used automatically for cca and decorana results, unless undone by the user. w=NULL sets equal weights to all points.
... Other parameters passed to graphical functions.

Details

Both function display three-dimensional ordination graphics. Function ordiplot3d plots static scatter diagrams using scatterplot3d. Function ordirgl plots dynamic graphics using OpenGL in rgl. Both functions use most default settings of underlying graphical functions, and you must consult their help pages to change graphics to suit your taste (see scatterplot3d, rgl, rgl.points,rgl.texts). Both functions will display only one selected set of scores, typically either "sites" or "species", but for instance cca also has "lc" scores. In constrained ordination (cca, rda, capscale), biplot arrows and centroids are always displayed similarly as in two-dimensional plotting function plot.cca. Alternatively, it is possible to display fitted environmental vectors or class centroids from envfit in both graphs. These are displayed similarly as the results of constrained ordination, and they can be shown only for non-constrained ordination. The user must remember to specify at least three axes in envfit if the results are used with these functions.

Function ordiplot3d plots only points. However, it returns invisibly an object inheriting from ordiplot so that you can use identify.ordiplot to identify "points" or "arrows". The underlying scatterplot3d function accepts type = "n" so that only the axes, biplot arrows and centroids of environmental variables will be plotted, and the ordination scores can be added with text.ordiplot or points.ordiplot. Further, you can use any functions from the ordihull family with the invisible result of ordiplot3d, but you must remember to specify the display as "points" or "arrows". To change the viewing angle, orientation etc. you must see scatterplot3d.

Function ordigl makes a dynamic three-dimensional graph that can be rotated with mouse, and zoomed into with mouse buttons or wheel (but Mac users with one-button mouse should see rgl.viewpoint), or try ctrl-button. MacOS X users must start X11 before calling rgl commands. Function ordirgl uses default settings, and you should consult the underlying functions rgl.points, rgl.texts to see how to control the graphics. Function ordirgl always cleans its graphic window before drawing. Functions orglpoints adds points and orgltext adds text to existing ordirgl windows. In addition, function orglsegments combines points within "groups" with line segments similarly as ordisegments. Function orglspider works similarly as ordispider: it connects points to their weighted centroid within "groups", and in constrained ordination it can connect "wa" or weighted averages scores to corresponding "lc" or linear combination scores if "groups" is missing. In addition, basic rgl functions rgl.points, rgl.texts, rgl.lines and many others can be used.

Value

Function ordiplot3d returns invisibly an object of class "ordiplot3d" inheriting from ordiplot. The return object will contain the coordinates projected onto two dimensions for "points", and possibly for the heads of "arrows" and "centroids" of environmental variables. Functions like identify.ordiplot, points.ordiplot, text.ordiplot can use this result, as well as ordihull and other functions documented with the latter. In addition, the result will contain the object returned by scatterplot3d, including function xyz.converter which projects three-dimensional coordinates onto the plane used in the current plot. Function ordirgl returns nothing.

Warning

Function ordirgl uses OpenGL package rgl which may not be functional in all platforms, and can crash R in some: use save.image before trying ordirgl. Mac users must start X11 (and first install X11 and some other libraries) before being able to use rgl. It seems that rgl.texts does not always position the text like supposed, and it may be safe to verify text location with corresponding points.

Note

The user interface of rgl changed in version 0.65, but the ordirgl functions do not yet fully use the new capabilities. However, they should work both in old and new versions of rgl.

Author(s)

Jari Oksanen

See Also

scatterplot3d, rgl, rgl.points, rgl.texts, rgl.viewpoint, ordiplot, identify.ordiplot, text.ordiplot, points.ordiplot, ordihull, plot.cca, envfit.

Examples

## Examples are not run, because they need non-standard packages
## 'scatterplot3d' and 'rgl' (and the latter needs user interaction).
#####
#### Default 'ordiplot3d'
## Not run: 
data(dune)
data(dune.env)
ord <- cca(dune ~ A1 + Moisture, dune.env)
ordiplot3d(ord)
#### A boxed 'pin' version
ordiplot3d(ord, type = "h")
#### More user control
pl <- ordiplot3d(ord, angle=15, type="n")
points(pl, "points", pch=16, col="red", cex = 0.7)
#### identify(pl, "arrows", col="blue") would put labels in better positions
text(pl, "arrows", col="blue", pos=3)
text(pl, "centroids", col="blue", pos=1, cex = 1.2)
#### ordirgl
ordirgl(ord, size=2)
ordirgl(ord, display = "species", type = "t")
rgl.quit()
## End(Not run)

[Package vegan version 1.16-32 Index]