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)
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.
"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.
TRUE
, the items in each column
are aligned horizontally.
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.
TRUE
is equivalent to
1
if
background=0
, and otherwise matches the
background
color.
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.
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.
type="b"
or
type="o"
.
TRUE
, the key is
transparent and lets the underlying plot show through. The default is
FALSE
and results in a solid background.
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.
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.
FALSE
, the key is not drawn. Instead, the size of the key box in inches is returned.
key
argument to a Trellis function.
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.
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.
# 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)