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 supress labels.
`justify, adj` | Text justification passed to `rgl.texts`. One of these is used depending on the versionof 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 invisble 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 capablities. 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.8-8 Index]