| % File src/library/graphics/man/symbols.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2012 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{symbols} |
| \alias{symbols} |
| \concept{circle} |
| \concept{star} |
| \concept{square} |
| \concept{rectangle} |
| \concept{thermometer} |
| \concept{boxplot} |
| \title{Draw Symbols (Circles, Squares, Stars, Thermometers, Boxplots)} |
| \description{ |
| This function draws symbols on a plot. One of six symbols; |
| \emph{circles}, \emph{squares}, \emph{rectangles}, \emph{stars}, |
| \emph{thermometers}, and \emph{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. |
| } |
| \usage{ |
| symbols(x, y = NULL, circles, squares, rectangles, stars, |
| thermometers, boxplots, inches = TRUE, add = FALSE, |
| fg = par("col"), bg = NA, |
| xlab = NULL, ylab = NULL, main = NULL, |
| xlim = NULL, ylim = NULL, \dots) |
| } |
| \arguments{ |
| \item{x, y}{the x and y co-ordinates for the centres of the symbols. |
| They can be specified in any way which is accepted by |
| \code{\link{xy.coords}}.} |
| \item{circles}{a vector giving the radii of the circles.} |
| \item{squares}{a vector giving the length of the sides of the squares.} |
| \item{rectangles}{a matrix with two columns. The first column gives |
| widths and the second the heights of rectangles.} |
| \item{stars}{a matrix with three or more columns giving the lengths |
| of the rays from the center of the stars. \code{NA} values |
| are replaced by zeroes.} |
| \item{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 \code{fg}) from their base to |
| this proportion of their height. If there are four columns, the |
| third and fourth columns are taken as proportions and the |
| thermometers are filled between these two proportions of their |
| heights. The part of the box not filled in \code{fg} will be filled |
| in the background colour (default transparent) given by \code{bg}.} |
| \item{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.} |
| \item{inches}{\code{TRUE}, \code{FALSE} or a positive number. |
| See \sQuote{Details}.} |
| \item{add}{if \code{add} is \code{TRUE}, the symbols are added to |
| an existing plot, otherwise a new plot is created.} |
| \item{fg}{colour(s) the symbols are to be drawn in.} |
| \item{bg}{if specified, the symbols are filled with colour(s), the |
| vector \code{bg} being recycled to the number of symbols. |
| The default is to leave the symbols unfilled.} |
| \item{xlab}{the x label of the plot if \code{add} is not true. |
| Defaults to the \code{\link{deparse}}d expression used for \code{x}.} |
| \item{ylab}{the y label of the plot. Unused if \code{add = TRUE}.} |
| \item{main}{a main title for the plot. Unused if \code{add = TRUE}.} |
| \item{xlim}{numeric vector of length 2 giving the x limits for the |
| plot. Unused if \code{add = TRUE}.} |
| \item{ylim}{numeric vector of length 2 giving the y limits for the |
| plot. Unused if \code{add = TRUE}.} |
| \item{\dots}{graphics parameters can also be passed to this function, |
| as can the plot aspect ratio \code{asp} (see \code{\link{plot.window}}).} |
| } |
| \details{ |
| Observations which have missing coordinates or missing size |
| parameters are not plotted. The exception to this is \emph{stars}. |
| In that case, the length of any ray which is \code{NA} is reset |
| to zero. |
| |
| Argument \code{inches} controls the sizes of the symbols. If |
| \code{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 \code{TRUE} and \code{1} are equivalent). If \code{inches} |
| is \code{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 \code{inches}, |
| and are otherwise interpreted in the units of the y axis.) |
| |
| % The next is enforced in GCircle. |
| Circles of radius zero are plotted at radius one pixel (which is |
| device-dependent). Circles of a very small non-zero radius may or may |
| not be visible, and may be smaller than circles of radius zero. On |
| \code{windows} devices circles are plotted at radius at least one |
| pixel as some Windows versions omit smaller circles. |
| } |
| \references{ |
| Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) |
| \emph{The New S Language}. |
| Wadsworth & Brooks/Cole. |
| |
| W. S. Cleveland (1985) |
| \emph{The Elements of Graphing Data.} |
| Monterey, California: Wadsworth. |
| |
| Murrell, P. (2005) \emph{R Graphics}. Chapman & Hall/CRC Press. |
| } |
| \seealso{ |
| \code{\link{stars}} for drawing \emph{stars} with a bit more |
| flexibility. |
| |
| If you are thinking about doing \sQuote{bubble plots} by |
| \code{symbols(*, circles=*)}, you should \emph{really} consider using |
| \code{\link{sunflowerplot}} instead. |
| } |
| \examples{ |
| 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) |
| }) |
| } |
| \keyword{aplot} |
| \keyword{hplot} |
| \keyword{multivariate} |