points               package:graphics               R Documentation

Add Points to a Plot

Description:

     'points' is a generic function to draw a sequence of points at the
     specified coordinates.  The specified character(s) are plotted,
     centered at the coordinates.

Usage:

     points(x, ...)

     ## Default S3 method:
     points(x, y = NULL, type = "p", pch = par("pch"),
            col = par("col"), bg = NA, cex = 1, ...)

Arguments:

    x, y: coordinate vectors of points to plot.

    type: character indicating the type of plotting; actually any of
          the 'type's as in 'plot'.

     pch: plotting "character", i.e., symbol to use.  'pch' can either
          be a 'character' or an integer code for a set of graphics
          symbols.  The full set of S symbols is available with
          'pch=0:18', see the last picture from 'example(points)',
          i.e., the examples below.

          In addition, there is a special set of R plotting symbols
          which can be obtained with 'pch=19:25' and '21:25' can be
          colored and filled with different colors:

             *  'pch=19': solid circle,

             *  'pch=20': bullet (smaller circle),

             *  'pch=21': circle,

             *  'pch=22': square,

             *  'pch=23': diamond,

             *  'pch=24': triangle point-up,

             *  'pch=25': triangle point down.

          Values 'pch=26:32' are currently unused, and 'pch=32:255'
          give the text symbol in the encoding in use (see
          'postscript'). 

     col: color code or name, see 'par'.

      bg: background ("fill") color for open plot symbols

     cex: character expansion: a numerical vector.

     ...: Further graphical parameters (see 'plot.xy' and 'par') may
          also be supplied as arguments.

Details:

     The coordinates can be passed in a plotting structure (a list with
     'x' and 'y' components), a two-column matrix, a time series, .... 
     See 'xy.coords'.

     Arguments 'pch', 'col', 'bg' and 'cex' can be vectors (which will
     be recycled as needed) giving a value for each point plotted. 
     Points whose 'x', 'y', 'pch', 'col' or 'cex' value is 'NA' are
     omitted from the plot.

     Graphical parameters are permitted as arguments to this function.

References:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

See Also:

     'plot', 'lines', and the underlying "primitive" 'plot.xy'.

Examples:

     plot(-4:4, -4:4, type = "n")# setting up coord. system
     points(rnorm(200), rnorm(200), col = "red")
     points(rnorm(100)/2, rnorm(100)/2, col = "blue", cex = 1.5)

     op <- par(bg = "light blue")
     x <- seq(0,2*pi, len=51)
     ## something "between type='b' and type='o'":
     plot(x, sin(x), type="o", pch=21, bg=par("bg"), col = "blue", cex=.6,
      main='plot(..., type="o", pch=21, bg=par("bg"))')
     par(op)

     ##-------- Showing all the extra & some char graphics symbols ------------
     Pex <- 3 ## good for both .Device=="postscript" and "x11"
     ipch <- 1:(np <- 25+11); k <- floor(sqrt(np)); dd <- c(-1,1)/2
     rx <- dd + range(ix <- (ipch-1) %/% k)
     ry <- dd + range(iy <- 3 + (k-1)-(ipch-1) %% k)
     pch <- as.list(ipch)
     pch[25+ 1:11] <- as.list(c("*",".", "o","O","0","+","-",":","|","%","#"))
     plot(rx, ry, type="n", axes = FALSE, xlab = "", ylab = "",
          main = paste("plot symbols :  points (...  pch = *, cex =", Pex,")"))
     abline(v = ix, h = iy, col = "lightgray", lty = "dotted")
     for(i in 1:np) {
       pc <- pch[[i]]
       points(ix[i], iy[i], pch = pc, col = "red", bg = "yellow", cex = Pex)
       ## red symbols with a yellow interior (where available)
       text(ix[i] - .3, iy[i], pc, col = "brown", cex = 1.2)
     }

