Put a Key or Legend on a Plot

USAGE:

key(x = <<see below>>, y = <<see below>>, 
    ..., <<... is any of: text, points, lines, rectangles>>, 
    title="", align=T, background=0, border=0, between=2, 
    corner=<<see below>>, divide=3, transparent=F, 
    cex, cex.title=1.5 * max(cex), 
    col, lty, lwd, font, pch, adj=0, type="l", size=5, 
    columns=1, between.columns=3, 
    angle=0, density=-1, plot=T, 
    space = NULL, text.width.multiplier=1)

ARGUMENTS:

x, y
location of the key. These coordinates, the corner argument, and the computed size of the key are all used to determine the location. If x and y are provided, the point on the key determined by the corner argument is placed at the point (x,y) on the graph. The default values put the key in the upper right of the plot region.
...
text
points
lines
rectangles
You must specify one or more of these arguments, and may repeat them. Each argument controls one column of the key. Columns appear in the key in the order they are specified in the argument list. The "points", "lines", or "rectangles" arguments should be lists containing vectors of graphical parameters that modify the rows in the column. A "text" argument may be a character vector, or a list whose first element is a character vector; additional elements may contain graphical parameters. The number of rows in the key is the larger of the lengths of any of the parameter vectors.
title
optional character string that specifies a title to be centered on the first line at the top of the key.
align
logical flag. If TRUE, the items in each column are aligned horizontally.
background
color of key background. Using background=0 effectively blanks out the key region, since color 0 is the same as the normal plot background. The transparent argument controls whether a key background is drawn.
border
color of the border around the key. This argument is normally supplied as a numeric value. However, a value of TRUE is equivalent to 1 if background=0, and otherwise matches the background color.
between
number of spaces between columns of the key. If between is a vector, the values indicate how much space is split on either side of each column. This results in between[1] spaces to the left of the first column, (between[1]+between[2])/2 spaces between the first and second columns, etc.
corner
vector of two fractions that tells which position of the key is referred to by the x,y arguments. For example, corner=c(0,1) means that x,y refers to the upper left of the key. The default is c(0,1) if x is supplied and c(1,1) otherwise. In addition, if x and y are missing, corner determines which corner of the plot region the key is placed in.
divide
number of point symbols that should divide each line symbol. This is important when type="b" or type="o".
transparent
logical value. If TRUE, the key is transparent and lets the underlying plot show through. The default is FALSE and results in a solid background.
cex
vector of character sizes. See the NOTES section below.
cex.title
character size for the title.
col
vector of color numbers. See the NOTES section below.
lty
vector of line types. See the NOTES section below.
lwd
vector of line widths. See the NOTES section below.
font
vector of font numbers. See the NOTES section below.
pch
character vector, each element giving one plotting character. See the NOTES section below.
adj
vector of character string adjustments. A value of 0 corresponds to left-justification, 1 corresponds to right-justification, and 0.5 corresponds to centered text. See the NOTES section below.
type
vector of character strings giving the way in which lines arguments are drawn:

"l" indicates lines.

"p" indicates points. Because of the between argument, the effect of type="p" is somewhat different than using a points argument.

"b" indicates both points and lines.

"o" indicates overlaid points and lines.

"n" indicates nothing is to be drawn.

See the NOTES section below for more details.
size
vector of sizes, in character widths, to control lines and rectangles.
columns
number of column-blocks the key should be divided into. Each of the column-blocks consists of some number of columns, corresponding to the number of text, points, lines and rectangles arguments. The whole key is computed and then divided into columns equal-length column-blocks that are then displayed side by side.
between.columns
spacing between column-blocks, in units of character width.
angle
vector giving the angle of shading lines for rectangles, measured in degrees counterclockwise from horizontal.
density
vector giving density of shading lines in lines per inch. Negative values imply a solid fill of rectangles.
plot
logical flag. If FALSE, the key is not drawn. Instead, the size of the key box in inches is returned.
space
used by Trellis functions to position the key. The documentation for explains how to use this argument with the key argument to a Trellis function.
text.width.multiplier
constant that can be used to adjust the spacing allowed for text. A value less than 1 allows less horizontal space for text strings.

VALUE:

if plot is FALSE, a vector of 2 numbers is returned, giving the width and height of the key in inches. This can be used to allocate space.

SIDE EFFECTS:

an appropriate key is drawn on the plot.

NOTES:

Trellis functions have a key argument that calls this function to produce a key. The list passed to a Trellis function's key argument becomes the list of arguments to this function.

In determining the graphical parameters to use for any particular item, the most important value is the one specified in closest proximity to the item. For example, colors specified in a text argument are used in preference to the overall col argument, which, in turn, are used rather than the current value of the col graphical parameter. Values of graphical parameters are reused cyclically. All graphical parameters given to key may be vectors with multiple values.

For Trellis plots, the trellis.par.get function provides graphical parameters used in the plot. These may be passed to key to be used in the legend. See the documentation for for a list of the graphical parameters it can provide.

S device functions are not always precisely able to determine the length of character strings in proportionally spaced fonts. Thus, strings that are not left-justified may be slightly out of alignment and the use of small values for between may be problematic.

SEE ALSO:

The function is an older, less flexible way of producing a key.

EXAMPLES:

# Create an arbitrary plot.
plot(0:1, 0:1)  
key( 
    text = list(month.name[1:5], adj = 1, col=1:5), 
    rectangles = list(size = 5, col=1:5), 
    line = list(lty = 2:6, lwd = 4, col=1:5)
)

# The second column includes both point and line symbols. 
# The key is placed in the lower left corner. 
key(corner = c(0,0),
    text = list(c("Cities", "Roads")), 
    lines = list(type = c("p", "l")),
    border = T
) 

# This key is placed in the top left corner.
key(text = list(state.name[1:5]), 
    lines = list(lty = 1:5, type = "o", pch = 1:5), 
    text = list(state.name[1:5], col = 1, font = 2, adj = 1), 
    points = list(pch = list("X",1,"*",".")), 
    rectangles = list(size = 3), 
    title = "Testing", 
    col = 1:5, 
    cex = 1:5/3, 
    font = 1:5, corner = c(0, 1),  
    size = 10, border = T, 
    between = 6)