Put a Legend on a Plot

DESCRIPTION:

Adds a legend to the current plot. The location and contents of the legend can be specified.

USAGE:

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) 

REQUIRED ARGUMENTS:

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.

OPTIONAL ARGUMENTS:

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
The fill color for the legend's boxes. Can be an integer vector of colors--for example, 2:4, a vector of named colors--for example, c("blue","green","purple"), a vector of hex values, or a combination--for example, c("#FF3355","green","#8899FF"). If you specify no fill argument, the legend boxes are not drawn.
col
integer vector, vector of named colors, or combination of the two (see fill above) to give 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 ). In particular, the bty parameter may be used to suppress the box surrounding the legend ( bty="n").

SIDE EFFECTS:

legend draws a box at specified coordinates and puts inside (if possible) examples of lines, points, marks, and/or shading, each identified with a user-specified text string.

DETAILS:

The values of the legend are displayed from the top to the bottom. If you are adding a legend to a vertical barplot, you will need to reverse the order of the legend.

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=" 11" is pch=9 and pch="\102" is pch="B".

SEE ALSO:

, , , , , , , , . In particular, function is more powerful and flexible than .

EXAMPLES:

# locator allows you to click on plot 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 
par(col = "green") # make the legend color green 
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 = " 46") # plot an ampersand ("&") 
                                      # using octal representation 
# the legend can be written (at least!) three different ways: 
legend(1,20,c("DG","C","A"), pch = " 107 46") # using pch only,  
   # here " 10" is the octal representation of pch=8. 
legend(1,20,c("DG","C","A"), marks = c(8,-1,-1), pch = " 7 46") 
   # 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  46 (ampersand) map to decimal values in marks 
#In this example, the colors are specified by name.
plot(freeny.x[,1], ylim = c(1,10), pch = 15, col = "blue") 
points(freeny.x[,2], pch = 15, col = "green") 
points(freeny.x[,3], pch = 15, col = "purple") 
typ.names <- c("price index", "income level", "market potential") 
# The fill argument specifies a vector of three colors,
# specified by name.
legend(25, 3, legend = typ.names, fill = c("blue","green","purple"))
# alternatively, you could specify the vector of colors using RGB or
# hex values, or a combination. For example, 
# fill = c("#FF3355","green","#8899FF")