cloud {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))

[Package Contents]