Draw Symbols on a Plot
DESCRIPTION:
Plots three-dimensional data on a two-dimensional plot by coding the third dimension with the size of a symbol plotted at each x-y location. The symbols can be circles, squares, rectangles, star plots, thermometers, or boxplots. The value of the argument specifying the symbol is a vector or matrix that determines the relative size of the symbols, while the inches argument controls overall size.
USAGE: 
symbols(x, y, circles, squares, rectangles, stars, thermometers,
        boxplots, add = F, inches = T)
REQUIRED ARGUMENTS:
x,y:
coordinates of points. The coordinates can be given by two arguments that are vectors or by a single argument x which is a univariate time series, a complex vector, a matrix with 2 columns, or a list containing components named x and y.
Missing values (NA) are allowed. Points containing missing values are not plotted.

Exactly one of the arguments circles, squares, rectangles, stars, thermometers, or boxplots must be given.

circles:
vector or matrix with one column containing the radii of the circles. Missing values are allowed, points containing missing values are not plotted.
squares:
vector or matrix with one column containing the lengths of the sides of the squares. Missing values are allowed, points containing missing values are not plotted.
rectangles:
matrix whose two columns give widths and heights of rectangles. Missing values are allowed, points containing missing values are not plotted.
stars:
matrix with n columns, where n is the number of points to a star. The matrix must be scaled from 0 to 1. Missing values are allowed, points containing missing values are treated as zero.
thermometers:
matrix with 3 or 4 columns. The first two columns give the widths and heights of the rectangular thermometer symbols. If the matrix has 3 columns, the third column gives the fraction of the symbol that is filled (from the bottom up). If the matrix has 4 columns, the third and fourth columns give the fractions of the rectangle between which it is filled. Missing values are allowed, points containing missing values are not plotted.
boxplots:
matrix with 5 columns of positive numbers, giving the width and height of the box, the amount to extend on the top and bottom, and the fraction of the way up the box to draw the median line. Missing values are allowed, points containing missing values are not plotted.
OPTIONAL ARGUMENTS:
add:
logical flag: if FALSE, a new plot is set up; if TRUE, symbols are added to the existing plot.
inches:
logical flag: if FALSE, the symbol parameters are interpreted as being in units of x and y. If TRUE, the symbols are scaled so that the largest symbol is approximately one inch in size. If a number is given, the parameters are scaled so that inches is the size of the largest symbol in inches.

Graphical parameters may also be supplied as arguments to this function (see par). In addition, the high-level graphics arguments described under par and the arguments to title may be supplied to this function.

NOTE:
The absolute size of the symbols on the plot is determined by the inches argument. The relative sizes are determined by the vector or matrix which specify the symbols.
SIDE EFFECTS:
This function creates or adds to a plot on the current device.
DETAILS:
Takes two objects and uses an argument to define a set of symbols to plot at the coordinates that the two objects define. If the add optional argument is set to TRUE, the symbols are added to the existing plot.
REFERENCES:
Cleveland, W. S. (1985). The Elements of Graphing Data. Wadsworth, Monterey, California.
BUGS:
The scaling for boxplots does not include the extent of the whiskers. Use the graphics parameter ylim to force the y-axis to include all of the whiskers.
SEE ALSO:
boxes , cbind , lines , names , par , stars , starsymb , subplot , text , title , usa .
EXAMPLES: 
# population of cities in US
select <- c("Atlanta", "Atlantic City", "Bismarck", "Boise", "Dallas",
            "Denver", "Lincoln", "Los Angeles", "Miami", "Milwaukee",
            "New York", "Seattle")
names(city.x) <- city.name
names(city.y) <- city.name
names(city.name) <- city.name
pop <- c(426, 60, 28, 34, 904, 494, 129, 2967, 347, 741, 7072, 557)
usa() # plot map of US
symbols(city.x[select], city.y[select], circles = sqrt(pop), add = T)
text(city.x[select], city.y[select], city.name[select], cex = size)


murder <- state.x77[,"Murder"]
west <- state.center$x < -95
therm <- cbind(.4, 1, murder[west]/max(murder[west]))
usa(xlim = c(94, 135), ylim = c(25, 52))
symbols(state.center$x[west], state.center$y[west],
        thermometers = therm, inches = .5, add = T)
title(main = "Murder Rates in the Western U.S.")