panel.cloud             package:lattice             R Documentation

Default Panel Function for cloud

Description:

     These are default panel functions controlling 'cloud' and
     'wireframe' displays.

Usage:

     panel.cloud(x, y, subscripts, z,
                 groups = NULL,
                 perspective = TRUE,
                 distance = if (perspective) 0.2 else 0, 
                 xlim, ylim, zlim,
                 panel.3d.cloud = "panel.3dscatter",
                 panel.3d.wireframe = "panel.3dwire",
                 screen = list(z = 40, x = -60),
                 R.mat = diag(4), aspect = c(1, 1),
                 par.box = NULL,
                 xlab, ylab, zlab,
                 xlab.default, ylab.default, zlab.default,
                 scales.3d,
                 proportion = 0.6,
                 wireframe = FALSE,
                 scpos,
                 ...,
                 at)
     panel.wireframe(...)
     panel.3dscatter(x, y, z, rot.mat, distance,
                     groups, type = "p",
                     xlim.scaled, ylim.scaled, zlim.scaled,
                     zero.scaled,
                     col, col.point, col.line,
                     lty, lwd, cex, pch,
                     cross, ..., subscripts)
     panel.3dwire(x, y, z, rot.mat = diag(4), distance,
                  shade = FALSE,
                  shade.colors.palette = trellis.par.get("shade.colors")$palette,
                  light.source = c(0, 0, 1000),
                  xlim.scaled,
                  ylim.scaled,
                  zlim.scaled,
                  col = if (shade) "transparent" else "black",
                  lty = 1, lwd = 1,
                  alpha,
                  col.groups = superpose.polygon$col,
                  polynum = 100,
                  ...,
                  drape = FALSE,
                  at,
                  col.regions = regions$col,
                  alpha.regions = regions$alpha)

Arguments:

 x, y, z: numeric (or possibly factors) vectors representing the data
          to be displayed. The interpretation depends on the context. 
          For 'panel.cloud' these are essentially the same as the data
          passed to the high level plot (except if 'formula' was a
          matrix, the appropriate 'x' and 'y' vectors are generated). 
          By the time they are passed to 'panel.3dscatter' and
          'panel.3dwire', they have been appropriately subsetted (using
          'subscripts') and scaled (to lie inside a bounding box,
          usually the [-0.5, 0.5] cube).

          Further, for 'panel.3dwire', 'x' and 'y' are shorter than 'z'
          and represent the sorted locations defining a rectangular
          grid. Also in this case, 'z' may be a matrix if the display
          is grouped, with each column representing one surface.

          In 'panel.cloud' (called from 'wireframe') and
          'panel.3dwire', 'x', 'y' and 'z' could also be matrices (of
          the same dimension) when they represent a 3-D surface
          parametrized on a 2-D grid. 

subscripts: index specifying which points to draw. The same 'x', 'y'
          and 'z' values (representing the whole data) are passed to
          'panel.cloud' for each panel.  'subscripts' specifies the
          subset of rows to be used for the particular panel. 

  groups: specification of a grouping variable, passed down from the
          high level functions. 

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

distance: numeric, between 0 and 1, controls amount of perspective. The
          distance of the viewing point from the origin (in the
          transformed coordinate system) is '1 / distance'. This is
          described in a little more detail in the documentation for
          'cloud' 

  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"' or '"z"' (repititions are
          allowed), with their values indicating the amount of rotation
          about that axis in degrees. 

   R.mat: initial rotation matrix in homogeneous coordinates, to be
          applied to the data before 'screen' rotates the view further. 

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

xlim, ylim, zlim: limits for the respective axes. As with other lattice
          functions, these could each be a numeric 2-vector or a
          character vector indicating levels of a factor. 

panel.3d.cloud, panel.3d.wireframe: functions that draw the data-driven
          part of the plot (as opposed to the bounding box and scales)
          in 'cloud' and 'wireframe'. This function is called after the
          'back' of the bounding box is drawn, but before the 'front'
          is drawn.

          Any user-defined custom display would probably want to change
          these functions. The intention is to pass as much information
          to this function as might be useful (not all of which are
          used by the defaults). In particular, these functions can
          expect arguments called 'xlim', 'ylim', 'zlim' which give the
          bounding box ranges in the original data scale and
          'xlim.scaled', 'ylim.scaled', 'zlim.scaled' which give the
          bounding box ranges in the transformed scale. More arguments
          can be considered on request. 

  aspect: aspect as in 'cloud' 

xlab, ylab, zlab: Labels, have to be lists. Typically the user will not
          manipulate these, but instead control this via arguments to
          'cloud' directly. 

xlab.default: for internal use  

ylab.default: for internal use  

zlab.default: for internal use  

scales.3d: list defining the scales 

proportion: numeric scalar, gives the length of arrows as a proportion
          of the sides 

   scpos: A list with three components x, y and z (each a scalar
          integer), describing which of the 12 sides of the cube the
          scales should be drawn. The defaults should be OK. Valid
          values are x: 1, 3, 9, 11; y: 8, 5, 7, 6 and z: 4, 2, 10, 12.
          (See comments in the source code of 'panel.cloud' to see the
          details of this enumeration.) 

wireframe: logical, indicating whether this is a wireframe plot

   drape: logical, whether the facets will be colored by height, in a
          manner similar to 'levelplot'.  This is ignored if
          'shade=TRUE'. 

at, col.regions, alpha.regions: deals with specification of colors when
          'drape = TRUE' in 'wireframe'.  'at' can be a numeric vector,
          'col.regions' a vector of colors, and 'alpha.regions' a
          numeric scalar controlling transparency.  The resulting
          behaviour is similar to 'levelplot', 'at' giving the
          breakpoints along the z-axis where colors change, and the
          other two determining the colors of the facets that fall in
          between. 

 rot.mat: 4x4 transformation matrix in homogeneous coordinates. This
          gives the rotation matrix combining the 'screen' and 'R.mat'
          arguments to 'panel.cloud' 

    type: character vector, specifying type of cloud plot. Can include
          one or more of '"p"', '"l"', '"h"' or '"b"'. '"p"' and '"l"'
          mean 'points' and 'lines' respectively, and '"b"' means
          'both'.  '"h"' stands for 'histogram', and causes a line to
          be drawn from each point to the X-Y plane (i.e., the plane
          representing 'z = 0'), or the lower (or upper) bounding box
          face, whichever is closer.

xlim.scaled, ylim.scaled, zlim.scaled: axis limits (after being scaled
          to the bounding box)  

zero.scaled: z-axis location (after being scaled to the bounding box)
          of the X-Y plane in the original data scale, to which lines
          will be dropped (if within range) from each point when 'type
          = "h"' 

   cross: logical, defaults to 'TRUE' if 'pch = "+"'. 'panel.3dscatter'
          can represent each point by a 3d 'cross' of sorts (it's much
          easier to understand looking at an example than from a
          description). This is different from the usual 'pch'
          argument, and reflects the depth of the points and the
          orientation of the axes. This argument indicates whether this
          feature will be used.

          This is useful for two reasons. It can be set to 'FALSE' to
          use '"+"' as the plotting character in the regular sense. It
          can also be used to force this feature in grouped displays. 

   shade: logical, indicating whether the surface is to be colored
          using an illumination model with a single light source 

shade.colors.palette: a function (or the name of one) that is supposed
          to calculate the color of a facet when shading is being used.
          Three pieces of information are available to the function:
          first, the cosine of the angle between the incident light ray
          and the normal to the surface (representing foreshortening);
          second, the cosine of half the angle between the reflected
          ray and the viewing direction (useful for non-Lambertian
          surfaces); and third, the scaled (average) height of that
          particular facet with respect to the total plot z-axis
          limits.

          All three numbers should be between 0 and 1. The
          'shade.colors.palette' function should return a valid color.
          The default function is obtained from the trellis settings. 

light.source: a 3-vector representing (in cartesian coordinates) the
          light source. This is relative to the viewing point being (0,
          0, 1/distance) (along the positive z-axis), keeping in mind
          that all observations are bounded within the [-0.5, 0.5] cube 

 polynum: quadrilateral faces are drawn in batches of 'polynum' at a
          time. Drawing too few at a time increases the total number of
          calls to the underlying 'grid.polygon' function, which
          affects speed. Trying to draw too many at once may be
          unnecessarily memory intensive. This argument controls the
          trade-off. 

col.groups: colors for different groups

col, col.point, col.line, lty, lwd, cex, pch, alpha: graphical
          parameters 

     ...: other parameters, passed down when appropriate

Details:

     These functions together are responsible for the content drawn
     inside each panel in 'cloud' and 'wireframe'. 'panel.wireframe' is
     a wrapper to 'panel.cloud', which does the actual work.

     'panel.cloud' is responsible for drawing the content that does not
     depend on the data, namely, the bounding box, the arrows/scales,
     etc. At some point, depending on whether 'wireframe' is TRUE, it
     calls either 'panel.3d.wireframe' or 'panel.3d.cloud', which draws
     the data-driven part of the plot.

     The arguments accepted by these two functions are different, since
     they have essentially different purposes. For cloud, the data is
     unstructured, and 'x', 'y' and 'z' are all passed to the
     'panel.3d.cloud' function. For wireframe, on the other hand, 'x'
     and 'y' are increasing vectors with unique values, defining a
     rectangular grid. 'z' must be a matrix with 'length(x) *
     length(y)' rows, and as many columns as the number of groups.

     'panel.3dscatter' is the default 'panel.3d.cloud' function. It has
     a 'type' argument similar to 'panel.xyplot', and supports grouped
     displays. It tries to honour depth ordering, i.e., points and
     lines closer to the camera are drawn later, overplotting more
     distant ones. (Of course there is no absolute ordering for line
     segments, so an ad hoc ordering is used. There is no hidden point
     removal.)

     'panel.3dwire' is the default 'panel.3d.wireframe' function. It
     calculates polygons corresponding to the facets one by one, but
     waits till it has collected information about 'polynum' facets,
     and draws them all at once. This avoids the overhead of drawing
     'grid.polygon' repeatedly, speeding up the rendering considerably.
     If 'shade = TRUE', these attempt to color the surface as being
     illuminated from a light source at 'light.source'. 'palette.shade'
     is a simple function that provides the deafult shading colors

     Multiple surfaces are drawn if 'groups' is non-null in the call to
     'wireframe', however, the algorithm is not sophisticated enough to
     render intersecting surfaces correctly.

Author(s):

     Deepayan Sarkar Deepayan.Sarkar@R-project.org

See Also:

     'cloud', 'utilities.3d'

