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", 
             ...)
     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: Text justification passed to 'rgl.texts'.

  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, and all 'X11' users must be aware of possibility
     of R crash with 'rgl.quit' or  'rgl.close'. 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.

_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)
     ## Not run: data(dune.env)
     ## Not run: ord <- cca(dune ~ A1 + Moisture, dune.env)
     ## Not run: ordiplot3d(ord)
     #### A boxed 'pin' version
     ## Not run: ordiplot3d(ord, type = "h")
     #### More user control
     ## Not run: pl <- ordiplot3d(ord, angle=15, type="n")
     ## Not run: points(pl, "points", pch=16, col="red", cex = 0.7)
     #### identify(pl, "arrows", col="blue") would put labels in better positions
     ## Not run: text(pl, "arrows", col="blue", pos=3)
     ## Not run: text(pl, "centroids", col="blue", pos=1, cex = 1.2)
     #### ordirgl
     ## Not run: ordirgl(ord, size=2)
     ## Not run: ordirgl(ord, display = "species", type = "t")
     ## Not run: rgl.quit() ## Safe with me, but may crash

