Perspective box: Creates an empty perspective box, ready for adding objects

Description

perspbox draws a box and labels, and makes space for a colorkey (if any).

Usage

perspbox (x = seq(0, 1, length.out = nrow(z)), 
          y = seq(0, 1, length.out = ncol(z)), z, 
          bty = c("b", "b2", "f", "g", "bl", "bl2", "u", "n"),  ..., 
          col.axis = "black", col.panel = NULL, lwd.panel = 1,                     
          col.grid = NULL, lwd.grid = 1, 
          phi = 40, theta = 40, col = NULL,
          colkey = NULL, plot = TRUE)

Arguments

x, y

Vectors with x and y values. It is sufficient to pass the ranges of the x- and y-values, as they will not be drawn. If z is a matrix, it is required that length(x) = nrow(z) and length(y) = ncol(z).

Matrix or vector with z-values. If z is a matrix, it is sufficient to pass a diagonal matrix with the range of the z-values, as they will not be drawn.

bty

The type of the box; only effective if the persp argument box equals TRUE (the default). Unless bty is equal to "u" then the arguments col.axis, col.panel, lwd.panel, col.grid, lwd.grid will be ignored. "f" is the full box, the default as from persp, "b" has only the back panels visible, when "b2" has back panels and grid lines, "g" has grey background with white gridlines, "bl" has a black background, "bl2" has a black background with grey lines. "u" means that the user will specify the arguments col.axis, col.panel, lwd.panel, col.grid, lwd.grid manually. "n" means that no box will be drawn. This is the same as setting box = FALSE.

col.axis, col.panel, col.grid

The color of the axis line, of the axis panel or of the grid lines. Only used if bty = "u".

lwd.panel, lwd.grid

The width of the panel border or of the grid lines. Only used if bty = "u".

theta, phi

The angles defining the viewing direction. theta gives the azimuthal direction and phi the colatitude. see persp.

col

Colors to be used for coloring the colvar variable. Here only used for assessing if a color key should be drawn.

colkey

A logical, NULL (default), or a list with parameters for the color key (legend). List parameters should be one of side, plot, length, width, dist, shift, addlines, col.clab, cex.clab, side.clab, line.clab, adj.clab, font.clab and the axis parameters at, labels, tick, line, pos, outer, font, lty, lwd, lwd.ticks, col.box, col.axis, col.ticks, hadj, padj, cex.axis, mgp, tck, tcl, las. The defaults for the parameters are side = 4, plot = TRUE, length = 1, width = 1, dist = 0, shift = 0, addlines = FALSE, col.clab = NULL, cex.clab = par("cex.lab"), side.clab = NULL, line.clab = NULL, adj.clab = NULL, font.clab = NULL) See colkey.

The default is to draw the color key on side = 4, i.e. in the right margin. If colkey = NULL then a color key will be added only if col is a vector. Setting colkey = list(plot = FALSE) will create room for the color key without drawing it. if colkey = FALSE, no color key legend will be added.

plot

Logical. If TRUE (default), a plot is created, otherwise the viewing transformation matrix is returned (as invisible).

…

additional arguments passed to persp.

The following persp arguments can be specified: xlim, ylim, zlim, xlab, ylab, zlab, main, sub, r, d, scale, expand, box, axes, nticks, ticktype.

Arguments scale and expand affect the size of the axes.

The arguments after … must be matched exactly.

Value

Function perspbox returns the viewing transformation matrix. See trans3D.

Details

The arguments xlim, ylim, zlim only affect the axes. All objects will be plotted, including those that fall out of these ranges. To select objects only within the axis limits, use plotdev.

The predefined box types bty are defined as follows:

``f'': all panels are shown and transparent, also the persp default.

``b'': only backward panels shown.

``b2'': as ``b'' with col.grid = "grey".

``g'': only backward panels shown; col.panel = grey(0.95), col.axis = "grey", lwd.grid = 2 and col.grid = "white".

``bl'': only backward panels shown; col.panel = "black", col.axis = "grey", lwd.grid = 2 and col.grid = "white".

``n'': no box is drawn.

Examples

Run this code

# NOT RUN {
# save plotting parameters                            
 pm   <- par("mfrow")
 pmar <- par("mar")

## ========================================================================
## The 4 predefined box types
## ========================================================================

 par(mfrow = c(2, 2), mar = c(1, 1, 1, 1))
 
# box type with only backward panels
 perspbox(z = volcano, bty = "b", ticktype = "detailed", d = 2, 
          main  = "bty = 'b'")
# box as in 'persp'
 perspbox(z = volcano, bty = "f", ticktype = "detailed", 
          d = 2, main  = "bty = 'f'")

# back panels with gridlines, detailed axes
 perspbox(z = volcano, bty = "b2", ticktype = "detailed", 
          d = 2, main  = "bty = 'b2'")

# ggplot-type, simple axes 
 perspbox(z = volcano, bty = "g", 
          d = 2, main  = "bty = 'g'")

## ========================================================================
## A user-defined box
## ========================================================================

 par(mfrow = c(1, 1))

 perspbox(z = diag(2), bty = "u", ticktype = "detailed", 
          col.panel = "gold", col.axis = "white",  
          scale = FALSE, expand = 0.4, 
          col.grid = "grey", main = "user-defined")

# restore plotting parameters
 par(mfrow = pm)
 par(mar = pmar)
# }

Run the code above in your browser using DataLab

State of Data and AI Literacy Report 2025