ordiplot3d               package:vegan               R Documentation

_T_h_r_e_e-_D_i_m_e_n_s_i_o_n_a_l _a_n_d _D_y_n_a_m_i_c _O_r_d_i_n_a_t_i_o_n _G_r_a_p_h_i_c_s

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

  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. 

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

     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.

_W_a_r_n_i_n_g:

     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.

_N_o_t_e:

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

_A_u_t_h_o_r(_s):

     Jari Oksanen

_S_e_e _A_l_s_o:

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

_E_x_a_m_p_l_e_s:

     ## 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)

