cloud                package:lattice                R Documentation

3d Scatter Plot

Description:

     Draws 3d scatter plots and surfaces.

Usage:

     cloud(formula,
           data,
           aspect = c(1, 1),
           scales = list(distance = rep(1, 3), arrows = TRUE),
           zlab,
           zlim, 
           distance = 0.2,
           par.box,
           perspective = TRUE,
           R.mat = diag(4), 
           screen = list(z = 40, x = -60),
           zoom = .9,
           ...)
     wireframe(formula, data,
               at = pretty(z, cuts),
               col.regions,
               drape = FALSE,
               shade = FALSE,
               pretty = FALSE,
               colorkey = any(drape),
               cuts = 70,
               distance = 0.2,
               par.box,
               screen = list(z = 40, x = -60),
               zoom,
               scales),
               ...)

Arguments:

 formula: a formula of the form 'z ~ x * y | g1 * g2 * ...', where 'z'
          is a numeric response, and 'x, y' are numeric values.
          'g1,g2,...', if present, are conditioning variables used for
          conditioning, and must be either factors or shingles. In the
          case of 'wireframe', calculations are based on the assumption
          the 'x' and 'y' values are evaluated on a rectangular grid
          (defined by their unique values). The grid points need not be
          equally spaced.

          For 'wireframe', 'x', 'y' and 'z' may also be matrices (of
          the same dimension), in which case they are taken to
          represent a 3-D surface parametrized on a 2-D grid (e.g., a
          sphere). Conditioning is not possible with this feature. See
          details below.

          Missing values are allowed, either as 'NA' values in the 'z'
          vector, or missing rows in the data frame (note however that
          in that case the X and Y grids will be determined only by the
          available values). For a grouped display (producing multiple
          surfaces), missing rows are not allowed, but 'NA''s in 'z'
          are.

          As an extension to partially support the form used in
          'filled.contour' and 'image', 'formula' can be a matrix. 

    data: data frame in which variables are evaluated

  aspect: vector of length 2, giving the relative aspects of the
          y-size/x-size and z-size/x-size of the enclosing rectangle.

  scales: describes scales. Can contain lists named x, y and z. Arrows
          are drawn if 'arrows=TRUE', otherwise tick marks with labels
          are drawn. Both can be suppressed by 'draw=FALSE'. Several
          other components that work in the usual 'scales' argument
          also work here (see 'xyplot'). 

    zlab: z label

    zlim: z limits

distance: numeric, between 0 and 1, controls amount of perspective. See
          details below 

 par.box: graphical parameters for box, namely, col, lty and lwd. By
          default obtained from the parameter 'box.3d' 

perspective: logical, whether to plot a perspective view. Setting this
          to 'FALSE' is equivalent to setting 'distance=0' 

   R.mat: initial rotation matrix in homogeneous coordinates.
          (Untested) 

  screen: A list determining the sequence of rotations to be applied to
          the data before being plotted. The initial position starts
          with the viewing point along the positive z-axis, and the x
          and y axes in the usual position. Each component of the list
          should be named one of 'x, y, z' (repititions are allowed),
          with their values indicating the amount of rotation about
          that axis in degrees. 

    zoom: factor by which to scale the picture. Useful to get the
          variable names into the plot 

   drape: logical, whether the wireframe is to be draped in color

   shade: logical, whether the wireframe is to be illuminated from a
          light source. See 'panel.3dwire' for details 

at, col.regions: these arguments are analogous to those in 'levelplot'.
          if 'drape=TRUE', 'at' gives the vector of values where the
          colors change, and 'col.regions' the vector of colors to be
          used in that case 

    cuts: the default number of cutpoints if 'drape=TRUE'

  pretty: whether the cutpoints should be pretty

colorkey: whether a color key should be drawn alongside. See
          'levelplot' for details 

     ...: other arguments, passed to the panel function 

Details:

     These functions produce three dimensional plots in each panel. The
     orientation is obtained as follows: the data are scaled to fall
     within a bounding box that is contained in the [-0.5, 0.5] cube
     (even smaller for non-default values of 'aspect').  The viewing
     direction is given by a sequence of rotations specified by the
     'screen' argument, starting from the positive Z-axis. The viewing
     point (camera) is located at a distance of '1/distance' from the
     origin. If 'perspective=FALSE', 'distance' is set to 0 (i.e., the
     viewing point is at an infinite distance).

     'cloud' draws a 3-D Scatter Plot, while 'wireframe' draws a 3-D
     surface (usually evaluated on a grid). Multiple surfaces can be
     drawn by 'wireframe' using the 'groups' argument (although this is
     of limited use because the display is messed up when the surfaces
     intersect). Specifying 'groups' with 'cloud' results in a
     'panel.superpose'-like effect (via 'panel.3dscatter').

     'wireframe' can optionally render the surface as being illuminated
     by a light source (no shadows though). Details can be found in the
     help page for 'panel.3dwire'. Note that although arguments
     controlling these are actually arguments for the panel function,
     they can be supplied to 'cloud' and 'wireframe' directly.

     For single panel plots, 'wireframe' can also plot parametrized 3-D
     surfaces (i.e., functions of the form f(u,v) = (x(u,v), y(u,v),
     z(u,v)), where values of (u,v) lie on a rectangle. The simplest
     example of this sort of surface is a sphere parametrized by
     latitude and longitude. This can be achieved by calling
     'wireframe' with a 'formula' of the form 'z~x*y', where 'x', 'y'
     and 'z' are all matrices of the same dimension, representing the
     values of x(u,v), y(u,v) and z(u,v) evaluated on a discrete
     rectangular grid (the actual values of (u,v) are unimportant). 

     When this feature is used, the heights used to calculate 'drape'
     colors or shading colors are no longer the 'z' values, but the
     distances of '(x,y,z)' from the origin.

     Note that this feature does not work with 'groups', 'subscripts',
     'subset', etc. Conditioning variables are also not supported in
     this case.

     The algorithm for identifying which edges of the bounding box are
     `behind' the points doesn't work in some extreme situations. Also,
     'panel.cloud' tries to figure out the optimal location of the
     arrows and axis labels automatically, but can fail on occasion
     (especially when the view is from ``below'' the data). This can be
     manually controlled by the 'scpos' argument in 'panel.cloud'.

     These and all other high level Trellis functions have several
     other arguments in common. These are extensively documented only
     in the help page for 'xyplot', which should be consulted to learn
     more detailed usage.

Value:

     An object of class ``trellis''. The `update' method can be used to
     update components of the object and the `print' method (usually
     called by default) will plot it on an appropriate plotting device.

Author(s):

     Deepayan Sarkar deepayan@stat.wisc.edu

See Also:

     'xyplot', 'levelplot', 'panel.cloud', 'Lattice'

Examples:

     data(volcano)  ## 87 x 61 matrix
     wireframe(volcano, shade = TRUE,
               aspect = c(61/87, 0.4),
               light.source = c(10,0,10))

     g <- expand.grid(x = 1:10, y = 5:15, gr = 1:2)
     g$z <- log((g$x^g$g + g$y^2) * g$gr)
     wireframe(z ~ x * y, data = g, groups = gr,
               scales = list(arrows = FALSE),
               drape = TRUE,
               screen = list(z = 30, x = -60))

     data(iris)
     cloud(Sepal.Length ~ Petal.Length * Petal.Width | Species, data = iris,
           screen = list(x = -90, y = 70), distance = .4, zoom = .6)

     par.set <- list(axis.line = list(col = "transparent"), clip = list(panel = FALSE))
     print(cloud(Sepal.Length ~ Petal.Length * Petal.Width, 
                 data = iris, cex = .8, 
                 groups = Species, 
                 subpanel = panel.superpose,
                 main = "Stereo",
                 screen = list(z = 20, x = -70, y = 3),
                 par.settings = par.set),
           split = c(1,1,2,1), more = TRUE)
     print(cloud(Sepal.Length ~ Petal.Length * Petal.Width,
                 data = iris, cex = .8, 
                 groups = Species,
                 subpanel = panel.superpose,
                 main = "Stereo",
                 screen = list(z = 20, x = -70, y = 0),
                 par.settings = par.set),
           split = c(2,1,2,1))

