ordirgl: Three-Dimensional Dynamic Ordination Graphics
In vegan3d: Static and Dynamic 3D and Editable Interactive Plots for the 'vegan' Package

ordirgl

R Documentation

Three-Dimensional Dynamic Ordination Graphics

Description

Function ordirgl displays three-dimensional dynamic ordination graphs which can be rotated and zoomed. This function works with all ordination results from vegan and all ordination results known by the scores function. The orgl-prefixed functions add elements to the ordirgl graph similarly as ordi-prefixed functions in vegan.

Usage

ordirgl(object, display = "sites", choices = 1:3, type = "p", col = "black",
    ax.col = "red", arr.col = "yellow", radius, text, envfit, ...)
orglpoints(object, display = "sites", choices = 1:3, radius, col = "black", ...)
orgltext(object, text, display = "sites", choices = 1:3, adj = 0.5,
    col = "black", ...)
orglsegments(object, groups, order.by, display = "sites", choices = 1:3,
    col = "black", ...)
orglspider(object, groups, display = "sites", w = weights(object, display),
    choices = 1:3, col = "black", ...)
orglellipse(object, groups, display = "sites", w = weights(object, display),
    kind = c("sd", "se", "ehull"), conf, choices = 1:3, alpha = 0.3,
    col = "red", ...)
orglspantree(object, spantree, display = "sites", choices = 1:3,
    col = "black", ...)
orglcluster(object, cluster, prune = 0, display = "sites", choices = 1:3,
    col = "black", ...)

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.
`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).
`arr.col`	Colour of biplot `arrows` and centroids of environmental variables.
`radius`	Size of points in the units of ordination scores.
`text`	Text to override the default with `type = "t"`.
`envfit`	Fitted environmental variables from `envfit` displayed in the graph. Use `envfit = NA` to suppress display of environmental variables in constrained ordination.
`adj`	Text justification passed to `text3d`.
`groups`	Factor giving the groups for which the graphical item is drawn.
`order.by`	Order points by this variable within `groups`.
`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.
`kind`	Draw ellipse for standard deviations of points (`"sd"`) or standard deviations of their averages (`"se"`) or an ellipsoid hull enclosing all points in the group (`"ehull"`.
`conf`	Confidence limit for ellipses, e.g., 0.95. If not given, sd or se ellipses are drawn.
`col`	Colour of items. This can be a vector and factors are interpreted as their internal numerical values. If the function has a `groups` argument, vector `col` is used for each of these, and for other functions it is matched to points in `ordirgl` (see Details below).
`alpha`	Transparency of colour between 0.0 (fully transparent) and 1.0 (non-transparent).
`spantree`	A minimum spanning tree object from vegan `spantree`.
`cluster`	Result of hierarchic cluster analysis, such as `hclust` or `agnes`.
`prune`	Number of upper levels hierarchies removed from the tree. If `prune` > 0, tree will be cut into `prune + 1` disconnected trees.
`...`	Other parameters passed to graphical functions.

Details

Function ordirgl plots dynamic graphics using OpenGL with the rgl package. It clears the graphics device and starts a new plot. The function was designed for ordination methods in the vegan package, but it can handle any method known to vegan scores function, or to any three column matrix. The orgl-prefixed functions add items to the opened rgl graphics device.

Function ordirgl uses most default settings of underlying graphical functions in rgl. It plots only one set of points, but functions orglpoints and orgltext can add new items to an existing plot. The points are plotted using spheres3d and the text using texts3d which both have their own configuration switches and their general look and feel can be modified with material3d. The point size is directly defined by radius argument in the units of ordination scores in spheres3d, but ordirgl uses a default size of 1% of the length of the longest axis, and this can be further modified by the cex multiplier.

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 orglsegments is similar to vegan ordisegments and connects points by line segments. This can be useful for regular transects. The colour of segments can be a vector which corresponds to the groups and will be recycled.

Function orglspider is similar as vegan 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. Function orglellipse is similar as vegan ordiellipse and draws ellipsoids of standard deviance, standard error or confidence regions for groups. At least four points are needed to define an ellipsoid in 3D, and even these will fail if all points are strictly on 2D. The col argument for both of these functions can be a vector corresponding to the groups.

Function orglspantree adds a minimum spanning tree from vegan spantree. This a 3D equivalent of lines.spantree. Function orglcluster adds a hierarchic cluster tree from hclust or related functions. This is a 3D equivalent of ordicluster. The col argument for both of these functions can be a vector corresponding to the connected points. In orglspantree the line colour is a mixture of colours of joined points, and in orglcluster it is a mixture of all points in the cluster.

Value

Function ordirgl returns nothing.

Warning

Function ordirgl uses OpenGL package rgl which may not be functional in all platforms.

Author(s)

Jari Oksanen

Examples


if (interactive() && require(rgl, quietly = TRUE)) {
data(mite, mite.env)
ord <- rda(decostand(mite, "hellinger"))
ordirgl(ord, size=4, col = "yellow")
orgltext(ord, display = "species")
## show groups of Shrub abundance
## ordirgl: col by points
with(mite.env, ordirgl(ord, col = as.numeric(Shrub), scaling = "sites"))
## orglspider & orglellipse: col by groups
with(mite.env, orglspider(ord, Shrub, col = 1:3, scaling = "sites"))
with(mite.env, orglellipse(ord, Shrub, col = 1:3, kind = "se", conf = 0.95,
    scaling = "sites"))
}

vegan3d documentation built on May 29, 2024, 9:49 a.m.