symbols               package:graphics               R Documentation

Draw Symbols (Circles, Squares, Stars, Thermometers, Boxplots) on a Plot

Description:

     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.

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

Arguments:

    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 'xy.coords'.

 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.  'NA' values are replaced
          by zeroes.

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 '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 'fg' will be filled in the background colour (default
          transparent) given by 'bg'.

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: 'TRUE', 'FALSE' or a positive number. See 'Details'.

     add: if 'add' is 'TRUE', the symbols are added to an existing
          plot, otherwise a new plot is created.

      fg: colour(s) the symbols are to be drawn in.

      bg: if specified, the symbols are filled with colour(s), the
          vector 'bg' being recycled to the number of symbols. The
          default is to leave the symbols unfilled.

    xlab: the x label of the plot if 'add' is not true. Defaults to the
          'deparse'd expression used for 'x'.

    ylab: the y label of the plot.  Unused if 'add = TRUE'.

    main: a main title for the plot.  Unused if 'add = TRUE'.

    xlim: numeric vector of length 2 giving the x limits for the plot. 
          Unused if 'add = TRUE'.

    ylim: numeric vector of length 2 giving the y limits for the plot. 
          Unused if 'add = TRUE'.

     ...: graphics parameters can also be passed to this function, as
          can the plot aspect ratio 'asp' (see 'plot.window').

Details:

     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
     device-dependent).

References:

     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.

See Also:

     '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.

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:
     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("default")
     })

