ordiplot3d: Three-Dimensional and Dynamic Ordination Graphics
In pattakosn/Rworkshop: Community Ecology Package

Description Usage Arguments Details Value Warning Note Author(s) See Also Examples

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.

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, ...)

`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.

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. Only one kind of scores will be plotted. See Examples for plotting both species and site scores.

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.

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 the projected coordinates of origin, and possibly the projected coordinates of 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. The result will also contain the object returned by scatterplot3d, including function xyz.convert which projects three-dimensional coordinates onto the plane used in the current plot (see Examples). In addition, there is a function envfit.convert that projects a three-dimensional envfit object to the current plot.

Function ordirgl returns nothing.

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.

Function ordiplot3d is based on scatterplot3d which does not allow exactly setting equal aspect ratio for axes. The function tries to circumvent this by setting equal plotting ranges for all axes so that the plot should be a cube. Depending on the dimensions of plotting device, this may fail, and the user should verify that the axes are approximately equal.

Please note that scatterplot3d sets internally some graphical parameters (such as mar for margins) and does not honour default settings. It is advisable to study carefully the documentation and examples of scatterplot3d.

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.

Jari Oksanen

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

## 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, scaling = 3, 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)
### Add species using xyz.convert function returned by ordiplot3d
sp <- scores(ord, choices=1:3, display="species", scaling=3)
text(pl$xyz.convert(sp), rownames(sp), cex=0.7, xpd=TRUE)
### Two ways of adding fitted variables to ordination plots
ord <- cca(dune)
ef <- envfit(ord ~ Moisture + A1, dune.env, choices = 1:3)
### 1. use argument 'envfit'
ordiplot3d(ord, envfit = ef)
### 2. use returned envfit.convert function for better user control
pl3 <- ordiplot3d(ord)
plot(pl3$envfit.convert(ef), at = pl3$origin)
### envfit.convert() also handles different 'choices' of axes
pl3 <- ordiplot3d(ord, choices = c(1,3,2))
plot(pl3$envfit.convert(ef), at = pl3$origin)
### ordirgl
ordirgl(ord, size=2)
ordirgl(ord, display = "species", type = "t")
rgl.quit()

## End(Not run)