TeachingDemos (version 2.3)

my.symbols: Draw Symbols (User Defined) on a Plot

Description

This function draws symbols on a plot. It is similar to the builtin symbols function with the difference that it plots symbols defined by the user rather than a prespecified set of symbols.

Usage

my.symbols(x, y=NULL, symb, inches=1, add=TRUE,
                       vadj=0.5, hadj=0.5,
                       symb.plots=FALSE,
                       xlab=deparse(substitute(x)),
                       ylab=deparse(substitute(y)), main=NULL,
                       xlim=NULL, ylim=NULL, ..., MoreArgs)

Arguments

x, y

The x and y coordinates for the position of the symbols to be plotted. These can be specified in any way which is accepted by xy.coords.

symb

Either a matrix, list, or function defining the symbol to be plotted. If it is a matrix or list it needs to be formatted that it can be passed directly to the lines function. It then defines the shape of the symbol on on a range/do

inches

The size of the square containing the symbol in inches (note: unlike symbols this cannot be FALSE).

add

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

vadj,hadj

Numbers between 0 and 1 indicating how 'x' and 'y' specify the location of the symbol. The defaults center the symbol at x,y; 0 means put the bottom/left at x,y; and 1 means put the top/right of the symbol at x,y.

symb.plots

If symb is a function that does its own plotting, set this to TRUE, otherwise it should be FALSE.

xlab, ylab, main, xlim, ylim

If 'add' is 'FALSE' these are passed to the plot function when setting up the plot.

...

Additional arguments will be replicated to the same length as x then passed to symb (if symb is a function) and/or the lines function (one value per symbol drawn).

MoreArgs

A list with any additional arguments to be passed to the symb function (as is, without being replicated/split).

Value

• This function is run for its side effect of plotting, it returns an invisible NULL.

Details

The symb argument can be a 2 column matrix or a list with components 'x' and 'y' that defines points on the interval [-1,1] that will be connected with lines to draw the symbol. If you want a closed polygon then be sure to replicate the 1st point as the last point. If any point contains an NA then the line will not be drawn to or from that point. This can be used to create a symbol with disjoint parts that should not be connected. If symb is a function then it should include a '...' argument along with any arguments to define the symbol. Any unmatched arguments that end up in the '...' argument will be replicated to the same length as 'x' (using the rep function) then the values will be passed one at a time to the symb function. If MoreArgs is specified, the elements of it will also be passed to symb without modification. The symb function can either return a matrix or list with the points that will then be passed to the lines function (see above). Or the function can call the plotting functions itself (set symb.plots to TRUE). High level plotting can be done (plot, hist, and other functions), or low level plotting functions (lines, points, etc) can be used; in this case they should add things to a plot with 'x' and 'y' limits of -1 to 1.

See Also

symbols, subplot, mapply, ms.polygram, lines

Examples

# symb is matrix

my.symbols( 1:10, runif(10), ms.male, add=FALSE, xlab='x',
  ylab='y', inches=0.3, col=c('blue','green'), xlim=c(0,11), ylim=c(-0.1,1.1))
my.symbols( (1:10)+0.5, runif(10), ms.female, add=TRUE, inches=0.3,
  col=c('red','green') )

# symb is function returning matrix

plot(1:10, 1:10)
my.symbols( 1:10, 1:10, ms.polygram, n=1:10, inches=0.3 )


# symb is plotting function
# create a variation on monthplot

fit <- lm( log(co2) ~ time(co2) )
fit.r <- resid(fit)

x <- 1:12
y <- tapply(fit.r, cycle(co2), mean)

tmp.r <- split( fit.r, cycle(co2) )
tmp.r <- lapply( tmp.r, function(x) x-mean(x) )

yl <- do.call('range',tmp.r)

tmpfun <- function(w,data,ylim,...){
  tmp <- data[[w]]
  plot(seq(along=tmp),tmp, type='l', xlab='',ylab='',
       axes=FALSE, ylim=ylim)
  abline(h=0, col='grey')
}

my.symbols(x,y, symb=tmpfun, inches=0.4, add=FALSE, symb.plots=TRUE,
  xlab='Month',ylab='Adjusted CO2', xlim=c(0.5,12.5),
  ylim=c(-0.012,0.012),
  w=1:12, MoreArgs=list(data=tmp.r,ylim=yl) )


# hand crafted hexagonal grid

x1 <- seq(0, by=2*sqrt(3), length.out=10)
y1 <- seq(0, by=3, length.out=10)

mypoints <- expand.grid(x=x1, y=y1)
mypoints[,1] <- mypoints[,1] + rep( c(0,sqrt(3)), each=10, length.out=100 )

plot(mypoints, asp=1, xlim=c(-2,35))
my.symbols(mypoints, symb=ms.filled.polygon, n=6,
  inches=par('pin')[1]/(diff(par('usr')[1:2]))*4,
  bg=paste('gray',1:100,sep=''), fg='green' )