Color key legend {plot3D}

Plots a color legend

Description

colkey plots a color legend, either to an existing plot or starting a new plot.

Usage

colkey (col = NULL, clim, clab = NULL, clog = FALSE, add = FALSE, 
        cex.clab = NULL, col.clab = NULL, side.clab = NULL, 
        line.clab = NULL, adj.clab = NULL, font.clab = NULL,
        side = 4, length = 1, width = 1, dist = 0, shift = 0,
        addlines = FALSE, breaks = NULL, at = NULL, labels = TRUE, tick = TRUE,
        line = NA, pos = NA, outer = FALSE, font = NA, lty = 1, lwd = 1, 
        lwd.ticks = 1, col.axis = NULL, col.ticks = NULL, col.box = NULL,
        hadj = NA, padj = NA, cex.axis = par("cex.axis"),
        mgp = NULL, tck = NULL, tcl = NULL, las = NULL) 

Arguments

col

Colors to be used for the color key. If col is NULL, then a red-yellow-blue colorscheme (jet.col) will be used.

clim

The range of the color values, used in the color key.

clab

The label to be written on top of the color key. The label will be written at the same level as the main title. To lower it, either clab can be made a vector, with the first values empty strings. Alternatively, it can be lowered by argument line.clab.

clog

If TRUE, then values of the color key will be log transformed.

add

If TRUE, the color key will be added to the current plot and positioned in the margin. If FALSE a new plot will be started and the color key will be positioned in the centre.

cex.clab

The size of the label written on top of the color key; default = same as axis labels.

col.clab

The color of the label written on top of the color key; default = same as main title.

side.clab

The side of the label written on top of the color key; default = same as main title, i.e. side = 3. Values of 1, 2, 4 will put the colorkey label at bottom, left and right of the key respectively.

line.clab

The numer of lines in the margin where the colorkey title is to be drawn. If unspecified, it is at line.clab =1.75.

adj.clab

The adjustment of the colorkey title, a number inbetween 0 (left) to 1 (right). The default is to put it central.

font.clab

The font of the colorkey title, a number inbetween 0 (left) to 1 (right). The default is to put it central.

side

Where to put the color key. 1 = bottom, 2 = left, 3 = top, 4 = right.

length

Relative length of the color key; 1 = same length as the axis.

width

Relative width of the color key.

dist

Distance of the color key to the margin. Positive values are further into the margin, negative values cause the color key to be positioned closer to or within the main plot. Reasonable range is [-0.5, 0.05].

shift

Shift relative to the centre. Positive values are upward when side = 2 or 4, and to the right for side = 1 or 3. It does not make sense to use this argument if length = 1. Reasonable range is [-0.2, 0.2].

addlines

If TRUE, will draw lines inbetween the colors.

breaks

a set of finite numeric breakpoints for the colors; must have one more breakpoint than color and be in increasing order. Unsorted vectors will be sorted, with a warning.

at, labels, tick, line, pos, outer, font, lty, lwd

Additional parameters as from the axis command.

lwd.ticks, hadj, padj, cex.axis, mgp, tck, tcl, las

Additional parameters as from the axis command.

col.box, col.axis, col.ticks

Additional parameters to set the color of the color legend framing box, the axis label and the axis ticks.

Author(s)

Karline Soetaert <[e-mail]>

Examples

# save plotting parameters
 pm <- par(mfrow = c(2, 2))
 pmar <- par(mar = c(5.1, 4.1, 4.1, 2.1))

## =======================================================================
##  colorkey as argument of a plot3D function
## =======================================================================
# default, colkey = NULL: adds colkey because multiple colors
 image2D(z = volcano)  

# default, colkey = NULL: no colkey because only one color
 image2D(z = volcano, col = "grey", shade = 0.2, contour = TRUE)  

# colkey = FALSE: no color key, no extra space foreseen
 image2D(z = volcano, colkey = FALSE)
 
# colkey = list(plot = FALSE): no color key, extra space foreseen
 image2D(z = volcano, colkey = list(plot = FALSE, side = 3))
 colkey (side = 3, add = TRUE, clim = range(volcano))
 
 
## =======================================================================
##  colorkey in new plot
## =======================================================================
 
 colkey(side = 1, clim = c(0, 1), add = FALSE, clab = "z", 
   col.clab = "red", adj.clab = 0)
 colkey(side = 2, clim = c(0, 1), clab = "z", length = 0.5, width = 0.5)
 colkey(side = 3, clim = c(0, 1), lwd = 3, clab = c("a","b","c","d"), 
   line.clab = 5)
 colkey(side = 4, clim = c(1e-6, 1), clog = TRUE, 
   clab = "a very long title in bold and close to the key", 
   line.clab = 1, side.clab = 2, font.clab = 2)

## =======================================================================
##  colorkey added to existing plot
## =======================================================================

 par(mfrow = c(1, 1))

 image2D(volcano, xlab = "", clab = "m", 
       colkey = list(side = 1, length = 0.5, width = 0.5, 
         line.clab = 1))
 colkey(side = 3, clim = range(volcano), add = TRUE)

# 'dist' to put colkey within the image 
# 'shift' to position colkey to the right or upward
 par(mfrow = c(1, 1))
 image2D(volcano, colkey = FALSE)

 colkey(clim = range(volcano), dist = -0.15, shift = 0.2,
        side = 3, add = TRUE, clab = "key 1", col.clab = "white",
        length = 0.5, width = 0.5, col.axis = "white", 
        col.ticks = "white", cex.axis = 0.8)

 colkey(clim = range(volcano), dist = -0.1, shift = -0.2,
        side = 4, add = TRUE, clab = "key 2", col.clab = "white",
        length = 0.3, width = 0.5, col.axis = "white", 
        col.ticks = "white", col.box = "red", cex.axis = 0.8)

 colkey(clim = range(volcano), dist = -0.3, 
        side = 1, add = TRUE, clab = "key 3", col.clab = "white",
        length = 0.3, width = 0.5, col.axis = "white", 
        col.ticks = "white", at  = c(100, 140, 180), 
        labels = c("a", "b", "c"), font = 2)

 colkey(clim = range(volcano), dist = -0.3, shift = -0.2,
        side = 2, add = TRUE, clab = "key 4", col.clab = "white",
        length = 0.3, width = 0.5, col.axis = "white", 
        col.ticks = "white", col.box = "red", cex.axis = 0.8,
        las = 3)

## =======================================================================
##  colorkey in other plots
## =======================================================================

 par(mfrow = c(1, 1))
 par(mar = par("mar") + c(0, 0, -2, 0))
 image2D(volcano, clab = "height, m", 
       colkey = list(dist = -0.15, shift = 0.2,
       side = 3, length = 0.5, width = 0.5, line.clab = 2.5,
       cex.clab = 2, col.clab = "white", col.axis = "white", 
       col.ticks = "white", cex.axis = 0.8))

## =======================================================================
## Several color keys in composite plot
## =======================================================================

 persp3D(z = volcano, zlim = c(-60, 200), phi = 20, bty = "b",   
    colkey = list(length = 0.2, width = 0.4, shift = 0.15,
      cex.axis = 0.8, cex.clab = 0.85), lighting = TRUE, lphi = 90,
    clab = c("height","m"), plot = FALSE)

# create gradient in x-direction
 Vx <- volcano[-1, ] - volcano[-nrow(volcano), ]

# add as image with own color key, at bottom 
 image3D(z = -60, colvar = Vx/10, add = TRUE, 
    colkey = list(length = 0.2, width = 0.4, shift = -0.15,
      cex.axis = 0.8, cex.clab = 0.85),
   clab = c("gradient","m/m"), plot = TRUE)

## =======================================================================
## categorical colors; use addlines = TRUE to separate colors
## =======================================================================

 with(iris, scatter3D(x = Sepal.Length, y = Sepal.Width, 
   z = Petal.Length, colvar = as.integer(Species), 
   col = c("orange", "green", "lightblue"), pch = 16, cex = 2,  
   clim = c(1, 3), ticktype = "detailed", phi = 20,
   xlab = "Sepal Length", ylab = "Sepal Width", 
   zlab = "Petal Length",  main = "iris",
   colkey = list(at = c(1.33, 2, 2.66), side = 1, 
   addlines = TRUE, length = 0.5, width = 0.5,
   labels = c("setosa", "versicolor", "virginica") )))

# reset plotting parameters
 par(mfrow = pm)
 par(mar = pmar)