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 vector arguments or by a single arguments x which is a times series, a two-column matrix, 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. In this case, circles and squares give ovals and rectangles when measured in inches.

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 ). In addition, the high-level graphics arguments described under and the arguments to may be supplied to this function.

Background color (bg) is used to fill the polygons (symbols) and foreground color (fg) to draw the edge (polylines). The col parameter is not used.

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:

, , , , , , , , , , .

EXAMPLES:

# population of cities in US 
select <- c("Atlanta", "Atlantic City", "Bismarck", "Boise", "Dallas", 
            "Denver", "Lincoln", "Los Angeles", "Miami", "Milwaukee", 
            "New York", "Seattle") 
# assign locally for modification
city.x <- city.x
city.y <- city.y
city.name <- city.name

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 = .5) 

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.") 

addCircles <- function(x, y, x.radii = NULL, y.radii=NULL, ...){
  # add circles to a plot, centers at (x,y),
  # radii specified in either x or y coordinates
  if(length(x.radii))
    symbols(x, y, circles = x.radii, add=T, ...,
            inches = max(x.radii) * par("uin")[1])
  else
    symbols(x, y, circles = y.radii, add=T, ...,
            inches = max(y.radii) * par("uin")[2])
}
plot(c(0,2), c(0,10))
symbols(1,1, circles=1, inches=F, add=T)
symbols(1,3, squares=1, inches=F, add=T)
addCircles(c(1,1), c(5,5), x.radii=c(.1,.2))
addCircles(c(1,1), c(7,7), y.radii=c(.1,.2))