This function draws symbols on a plot. One of six symbols; circles, squares, rectangles, stars, thermometers, and boxplots, can be plotted at a specified set of x and y coordinates. Specific aspects of the symbols, such as relative size, can be customized by additional parameters.
1 2 3 4 5 
x, y 
the x and y coordinates for the centres of the symbols.
They can be specified in any way which is accepted by

circles 
a vector giving the radii of the circles. 
squares 
a vector giving the length of the sides of the squares. 
rectangles 
a matrix with two columns. The first column gives widths and the second the heights of rectangles. 
stars 
a matrix with three or more columns giving the lengths
of the rays from the center of the stars. 
thermometers 
a matrix with three or four columns. The first
two columns give the width and height of the thermometer symbols. If
there are three columns, the third is taken as a proportion: the
thermometers are filled (using colour 
boxplots 
a matrix with five columns. The first two columns give the width and height of the boxes, the next two columns give the lengths of the lower and upper whiskers and the fifth the proportion (with a warning if not in [0,1]) of the way up the box that the median line is drawn. 
inches 

add 
if 
fg 
colour(s) the symbols are to be drawn in. 
bg 
if specified, the symbols are filled with colour(s), the
vector 
xlab 
the x label of the plot if 
ylab 
the y label of the plot. Unused if 
main 
a main title for the plot. Unused if 
xlim 
numeric vector of length 2 giving the x limits for the
plot. Unused if 
ylim 
numeric vector of length 2 giving the y limits for the
plot. Unused if 
... 
graphics parameters can also be passed to this function,
as can the plot aspect ratio 
Observations which have missing coordinates or missing size
parameters are not plotted. The exception to this is stars.
In that case, the length of any ray which is NA
is reset
to zero.
Argument inches
controls the sizes of the symbols. If
TRUE
(the default), the symbols are scaled so that the
largest dimension of any symbol is one inch. If a positive number is
given the symbols are scaled to make largest dimension this size in
inches (so TRUE
and 1
are equivalent). If inches
is FALSE
, the units are taken to be those of the appropriate
axes. (For circles, squares and stars the units of the x axis are
used. For boxplots, the lengths of the whiskers are regarded as
dimensions alongside width and height when scaling by inches
,
and are otherwise interpreted in the units of the y axis.)
Circles of radius zero are plotted at radius one pixel (which is
devicedependent). Circles of a very small nonzero radius may or may
not be visible, and may be smaller than circles of radius zero. On
windows
devices circles are plotted at radius at least one
pixel as some Windows versions omit smaller circles.
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.
W. S. Cleveland (1985) The Elements of Graphing Data. Monterey, California: Wadsworth.
Murrell, P. (2005) R Graphics. Chapman & Hall/CRC Press.
stars
for drawing stars with a bit more
flexibility.
If you are thinking about doing ‘bubble plots’ by
symbols(*, circles=*)
, you should really consider using
sunflowerplot
instead.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22  require(stats); require(grDevices)
x < 1:10
y < sort(10*runif(10))
z < runif(10)
z3 < cbind(z, 2*runif(10), runif(10))
symbols(x, y, thermometers = cbind(.5, 1, z), inches = .5, fg = 1:10)
symbols(x, y, thermometers = z3, inches = FALSE)
text(x, y, apply(format(round(z3, digits = 2)), 1, paste, collapse = ","),
adj = c(.2,0), cex = .75, col = "purple", xpd = NA)
## Note that example(trees) shows more sensible plots!
N < nrow(trees)
with(trees, {
## Girth is diameter in inches
symbols(Height, Volume, circles = Girth/24, inches = FALSE,
main = "Trees' Girth") # xlab and ylab automatically
## Colours too:
op < palette(rainbow(N, end = 0.9))
symbols(Height, Volume, circles = Girth/16, inches = FALSE, bg = 1:N,
fg = "gray30", main = "symbols(*, circles = Girth/16, bg = 1:N)")
palette(op)
})

Questions? Problems? Suggestions? Tweet to @rdrrHQ or email at ian@mutexlabs.com.
All documentation is copyright its authors; we didn't write any of that.