cloud                package:lattice                R Documentation

3d Scatter Plot and Wireframe Surface Plot

Description:

     Generic functions to draw 3d scatter plots and surfaces.  The
     '"formula"' methods do most of the actual work.

Usage:

     cloud(x, data, ...)
     wireframe(x, data, ...)

     ## S3 method for class 'formula':
     cloud(x,
           data,
           allow.multiple = is.null(groups) || outer,
           outer = FALSE,
           auto.key = FALSE,
           aspect = c(1,1),
           panel.aspect = 1,
           panel = lattice.getOption("panel.cloud"),
           prepanel = NULL,
           scales = list(),
           strip = TRUE,
           groups = NULL,
           xlab,
           ylab,
           zlab,
           xlim = if (is.factor(x)) levels(x) else range(x, finite = TRUE),
           ylim = if (is.factor(y)) levels(y) else range(y, finite = TRUE),
           zlim = if (is.factor(z)) levels(z) else range(z, finite = TRUE),
           at,
           drape = FALSE,
           pretty = FALSE,
           drop.unused.levels,
           ...,
           lattice.options = NULL,
           default.scales =
           list(distance = c(1, 1, 1),
                arrows = TRUE,
                axs = axs.default),
           colorkey,
           col.regions,
           alpha.regions,
           cuts = 70,
           subset = TRUE,
           axs.default = "r")

     ## S3 method for class 'formula':
     wireframe(x,
               data,
               panel = lattice.getOption("panel.wireframe"),
               ...)

     ## S3 method for class 'matrix':
     cloud(x, data = NULL, type = "h", 
           zlab = deparse(substitute(x)), aspect, ...,
           xlim, ylim, row.values, column.values)

     ## S3 method for class 'table':
     cloud(x, data = NULL, groups = FALSE,
           zlab = deparse(substitute(x)),
           type = "h", ...)

     ## S3 method for class 'matrix':
     wireframe(x, data = NULL,
               zlab = deparse(substitute(x)), aspect, ...,
               xlim, ylim, row.values, column.values)

Arguments:

       x: The object on which method dispatch is carried out.

          For the '"formula"' methods, 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 that 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.

          Both 'wireframe' and 'cloud' have methods for 'matrix'
          objects, in which case 'x' provides the 'z' vector described
          above, while its rows and columns are interpreted as the 'x'
          and 'y' vectors respectively.  This is similar to the form
          used in 'persp'. 

    data: for the '"formula"' methods, an optional data frame in which
          variables in the formula (as well as 'groups' and 'subset',
          if any) are to be evaluated.  'data' should not be specified
          except when using the '"formula"' method. 

row.values, column.values: Optional vectors of values that define the
          grid when 'x' is a matrix.  'row.values' and 'column.values'
          must have the same lengths as 'nrow(x)' and 'ncol(x)'
          respectively.  By default, row and column numbers. 

allow.multiple, outer, auto.key, prepanel, strip, groups, xlab,
xlim, ylab, ylim, drop.unused.levels, lattice.options,
default.scales, subset: 
          These arguments are documented in the help page for 'xyplot'.
           For the 'cloud.table' method, 'groups' must be a logical
          indicating whether the last dimension should be used as a
          grouping variable as opposed to a conditioning variable. 
          This is only relevant if the table has more than 2
          dimensions. 

    type: type of display in 'cloud' (see 'panel.3dscatter' for
          details).  Defaults to '"h"' for the 'matrix' method. 

aspect, panel.aspect: unlike other high level functions, 'aspect' is
          taken to be a numeric vector of length 2, giving the relative
          aspects of the y-size/x-size and z-size/x-size of the
          enclosing cube.  The usual role of the 'aspect' argument in
          determining the aspect ratio of the panel (see 'xyplot' for
          details) is played by 'panel.aspect', except that it can only
          be a numeric value.

          For the 'matrix' methods, the default y/x aspect is 'ncol(x)
          / nrow(x)' and the z/x aspect is the smaller of the y/x
          aspect and 1. 

   panel: panel function used to create the display.  See 'panel.cloud'
          for (non-trivial) details. 

  scales: a list describing the scales.  As with other high level
          functions (see 'xyplot' for details), this list can contain
          parameters in name=value form.  It can also contain
          components with the special names 'x', 'y' and 'z', which can
          be similar lists with axis-specific values overriding the
          ones specified in 'scales'. 

          The most common use for this argument is to set
          'arrows=FALSE', which causes tick marks and labels to be used
          instead of arrows being drawn (the default).  Both can be
          suppressed by 'draw=FALSE'.  Another special component is
          'distance', which specifies the relative distance of the axis
          label from the bounding box.  If specified as a component of
          'scales' (as opposed to one of 'scales$z' etc), this can be
          (and is recycled if not) a vector of length 3, specifying
          distances for the x, y and z labels respectively.

          Other components that work in the 'scales' argument of
          'xyplot' etc. should also work here (as long as they make
          sense), including explicit specification of tick mark
          locations and labels.  (Not everything is implemented yet,
          but if you find something that should work but does not, feel
          free to bug the maintainer.)

          Note, however, that for these functions 'scales' cannot
          contain information that is specific to particular panels. 
          If you really need that, consider using the 'scales.3d'
          argument of 'panel.cloud'. 

axs.default: Unlike 2-D display functions, 'cloud' does not expand the
          bounding box to slightly beyound the range of the data, even
          though it should.  This is primarily because this is the
          natural behaviour in 'wireframe', which uses the same code. 
          'axs.default' is intended to provide a different default for
          'cloud'. However, this feature has not yet been implemented. 

    zlab: Specifies a label describing the z variable in ways similar
          to 'xlab' and 'ylab' (i.e. "grob", character string,
          expression or list) in other high level functions. 
          Additionally, if 'zlab' (and 'xlab' and 'ylab') is a list, it
          can contain a component called 'rot', controlling the
          rotation for the label 

    zlim: limits for the z-axis. Similar to 'xlim' and 'ylim' in other
          high level functions 

   drape: logical, whether the wireframe is to be draped in color. If
          'TRUE', the height of a facet is used to determine its color
          in a manner similar to the coloring scheme used in
          'levelplot'.  Otherwise, the background color is used to
          color the facets.  This argument is ignored if 'shade = TRUE'
          (see 'panel.3dwire'). 

at, col.regions, alpha.regions: these arguments are analogous to those
          in 'levelplot'. if 'drape=TRUE', 'at' gives the vector of
          cutpoints where the colors change, and 'col.regions' the
          vector of colors to be used in that case.  'alpha.regions'
          determines the alpha-transparency on supporting devices. 
          These are passed down to the panel function, and also used in
          the colorkey if appropriate.  The default for 'col.regions'
          and 'alpha.regions' is derived from the Trellis setting
          '"regions"' 

    cuts: if 'at' is unspecified, the approximate number of cutpoints
          if 'drape=TRUE' 

  pretty: whether automatic choice of cutpoints should be prettfied 

colorkey: logical indicating whether a color key should be drawn
          alongside, or a list describing such a key.  See 'levelplot'
          for details. 

     ...: Any number of other arguments can be specified, and are
          passed to the panel function.  In particular, the arguments
          'distance', 'perspective', 'screen' and 'R.mat' are very
          important in determining the 3-D display.  The argument
          'shade' can be useful for 'wireframe' calls, and controls
          shading of the rendered surface.  These arguments are
          described in detail in the help page for 'panel.cloud'.

          Additionally, an argument called 'zoom' may be specified,
          which should be a numeric scalar to be interpreted as a scale
          factor by which the projection is magnified.  This can be
          useful to get the variable names into the plot.  This
          argument is actually only used by the default prepanel
          function. 

Details:

     These functions produce three dimensional plots in each panel (as
     long as the default panel functions are used).  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 incorrect 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 'x' 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 irrelevant).

     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.

Note:

     There is a known problem with grouped 'wireframe' displays when
     the (x, y) coordinates represented in the data do not represent
     the full evaluation grid.  The problem occurs whether the grouping
     is specified through the 'groups' argument or through the formula
     interface, and currently causes memory access violations. 
     Depending on the circumstances, this is manifested either as a
     meaningless plot or a crash.  To work around the problem, it
     should be enough to have a row in the data frame for each grid
     point, with an 'NA' response ('z') in rows that were previously
     missing.

Author(s):

     Deepayan Sarkar Deepayan.Sarkar@R-project.org

References:

     Sarkar, Deepayan (2008) "Lattice: Multivariate Data Visualization
     with R", Springer. <URL: http://lmdvr.r-forge.r-project.org/>

See Also:

     'Lattice' for an overview of the package, as well as  'xyplot',
     'levelplot', 'panel.cloud'

Examples:

     ## 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, colorkey = TRUE,
               screen = list(z = 30, x = -60))

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

     ## cloud.table

     cloud(prop.table(Titanic, margin = 1:3),
           type = c("p", "h"), strip = strip.custom(strip.names = TRUE),
           scales = list(arrows = FALSE, distance = 2), panel.aspect = 0.7,
           zlab = "Proportion")[, 1]

     ## transparent axes

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

