my.symbols           package:TeachingDemos           R Documentation

_D_r_a_w _S_y_m_b_o_l_s (_U_s_e_r _D_e_f_i_n_e_d) _o_n _a _P_l_o_t

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

     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)

_A_r_g_u_m_e_n_t_s:

    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/domain of
          -1 to 1.  If this is a function it can either return a matrix
          or list as above (points on the range/domain of -1 to 1), or
          it can do the plotting itself.

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

_D_e_t_a_i_l_s:

     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.

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

_V_a_l_u_e:

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

_N_o_t_e:

     Since the '...' argument is passed to both 'lines' and 'symb', the
     'symb' function should have a '...' argument so that it will
     ignore any additional arguments.

     Arguments such as 'type' can be passed through the '...' argument
     if you want the symbol made of something other than lines.

     Plotting coordinates and sizes are based on the size of the device
     at the time the function is called.  If you resize the device
     after plotting, all bets are off.

_A_u_t_h_o_r(_s):

     Greg Snow greg.snow@intermountainmail.org

_S_e_e _A_l_s_o:

     'symbols', 'subplot', 'mapply', 'ms.polygram', 'lines'

_E_x_a_m_p_l_e_s:

     # 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' )

