legend(x, y, legend, angle = <<see below>>, density = <<see below>>,
       fill = <<see below>>, col = <<see below>>, lty = <<see below>>,
       lwd = <<see below>>, marks = <<see below>>, pch = <<see below>>,
       ncol = 1, background = 0)

x,y:

location of the rectangle in which to put the legend. If x and y are length 1, they determine the top left corner of the rectangle; if they are length 2 vectors, they give opposite corners of the rectangular area. A list containing x and y values may be supplied.

legend:

vector of character strings to be associated with shading patterns, line types, plotting characters or marks.

angle:

vector giving the angle (in degrees counter-clockwise from horizontal) for shading each bar division. The default is 45 if density is supplied.

density:

vector for bar shading. If a positive number, the number of lines per inch for shading each bar division. The default is 5 if angle is supplied. The value 0 means a solidly filled box, -99 means no box, and other negative numbers means a hollow box.

fill:

integer vector of colors for filled boxes. The default is to use color 1 for (all) filled boxes.

col:

integer vector giving the colors in which the points and lines should be drawn. The default is to use the color in graphics parameter col for (all) points and lines.

lty:

integer vector of line types. If lty or lwd is specified, then lines are drawn. If lines are drawn, the default is to use the line type in graphics parameter lty for (all) lines.

lwd:

integer vector of line widths. If lty or lwd is specified, then lines are drawn. If lines are drawn, the default is to use the line width in graphics parameter lwd for (all) lines.

marks:

vector of plotting symbol numbers (see documentation for function lines). The default is not to draw marks.

pch:

character string of plotting characters. Single characters from pch will be used (see the example). Only the first element of a vector will be used. If you used the pch graphics parameter as a number, see the marks argument above. The default is not to draw plotting characters.

ncol:

number of columns in which the legend will be arranged, usually either 1 or the length of legend.

background:

color for the background of the legend. By default, the background color of the plot.

Graphical parameters may also be supplied as arguments to this function (see par). In particular, the bty parameter may be used to suppress the box surrounding the legend (bty="n").

Symbols in the legend can be specified in several different ways, depending on whether you choose to plot common plotting characters, letters or keyboard symbols (see below and the EXAMPLES section for details).

1) Symbols can be specified in the marks argument as a numeric vector of decimal numbers. The decimal number corresponding to a particular symbol can be found using the AsciiToInt function.

2) A combination of the marks and pch arguments can be used to specify plotting symbols. Use a negative number in marks every place you want to use a character in pch, and a blank space in pch every place you want to use a symbol in marks.

3) Symbols can be specified in the pch argument using a character string. In this case, all of the symbols have to be represented as characters, which can be done by converting them to three digit octal numbers preceded by a backslash. for example, pch="\011" is pch=9 and pch="\102" is pch="B".

# locator allows you to click on plot to to point at upper-left corner
# of area to contain the legend -- draw colored boxes
plot(freeny.x[,1], ylim = c(1:10), pch = 15, col = 2)
points(freeny.x[,2], pch = 15, col = 3)
points(freeny.x[,3], pch = 15, col = 4)
typ.names <- c("price index", "income level", "market potential")
legend(locator(1), legend = typ.names, fill = 2:4)

# draw legend with different line styles and plotting chars
tsplot(bonds.yield[1:40,], lty = 1:6)
par(col = 3) # make the legend in color 3
legend(13, .086, legend = as.character(bonds.coupon),
       lty = 1:6, pch = "OXAC*I")

# suppress the bounding box for the legend
legend(13, .086, legend = as.character(bonds.coupon),
       lty = 1:6, pch = "OXAC*I", bty = "n")

plot(testscores[,1], pch = 8) # use a decimal representation
points(testscores[,2], pch = "7") # plot a literal character
points(testscores[,3], pch = "\046") # plot an ampersand ("&")
                                      # using octal representation

# the legend can be written (at least!) three different ways:

legend(1,20,c("DG","C","A"), pch = "\0107\046") # using pch only,
   # here "\010" is the octal representation of pch=8.

legend(1,20,c("DG","C","A"), marks = c(8,-1,-1), pch = " 7\046")
   # the desired symbol is either represented in marks with a
   # blank space in pch or by pch with a "-1" in marks.

# use AsciiToInt to find decimal value for ascii characters:
AsciiToInt("7","&")

legend(1,20,c("DG","C","A"), marks = c(8,55,38))  # literal "7"
   # and octal \046 (ampersand) map to decimal values in marks