Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!
Get Started for Free

ordirgl

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 rgl.texts.

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 rgl.spheres and the text using rgl.texts which both have their own configuration switches and their general look and feel can be modified with rgl.material. The point size is directly defined by radius argument in the units of ordination scores in rgl.spheres, 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

See Also

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

Static and Dynamic 3D Plots for the 'vegan' Package

v1.1-2
GPL-2
Authors
Jari Oksanen [aut, cre], Roeland Kindt [aut], Gavin L. Simpson [aut]
Initial release
2018-10-25

We don't support your browser anymore

Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.