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

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

     ...: Further graphical parameters may also be supplied as
          arguments.  See 'Details'.

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

     Graphical parameters commonly used are

     'pch' plotting 'character', i.e., symbol to use.  This can either
          be a single character or an integer code for one of 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 a single-byte locale.  In a
          multi-byte locale such as UTF-8, numeric values of 'pch'
          greater than or equal to 32 specify a Unicode code point
          (except for the symbol font as selected by 'par(font = 5)').

          If 'pch' is an integer or character 'NA' or an empty
          character string, the point is omitted from the plot.

          Value 'pch="."' is handled specially.  It is a rectangle of
          side 0.01 inch (scaled by 'cex').  In addition, if 'cex = 1'
          (the default), each side is at least one pixel (1/72 inch on
          the 'pdf', 'postscript' and 'xfig' devices).

          For other text symbols, 'cex=1' corresponds to the default
          fontsize of the device, often specified by an argument
          'pointsize'. For 'pch' in '1:25' the default size is about
          75% of the character height (see 'par("cin")').

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

     'bg' background (fill) color for the open plot symbols given by
          'pch=21:25'.

     'cex' character (or symbol) expansion: a numerical vector. This
          works as a multiple of 'par("cex")'.

     'lwd' line width for drawing symbols see 'par'.

     Others less commonly used are 'lty' and 'lwd' for types such as
     '"b"' and '"l"'.

     Graphical parameters 'pch', 'col', 'bg', 'cex' and 'lwd' can be
     vectors (which will be recycled as needed) giving a value for each
     point plotted.  If lines are to be plotted (e.g. for 'type = "b"'
     the first element of 'lwd' is used.

     Points whose 'x', 'y', 'pch', 'col' or 'cex' value is 'NA' are
     omitted from the plot.

Note:

     What is meant by 'a single character' is locale-dependent.

     The encoding may not have symbols for some or all of the
     characters in 'pch=128:255'

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 workhorse function 'plot.xy'.

Examples:

     require(stats) # for rnorm
     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 ------------
     pchShow <-
       function(extras = c("*",".", "o","O","0","+","-","|","%","#"),
                cex = 3, ## good for both .Device=="postscript" and "x11"
                col = "red3", bg = "gold", coltext = "brown", cextext = 1.2,
                main = paste("plot symbols :  points (...  pch = *, cex =", cex,")"))
       {
         nex <- length(extras)
         np  <- 26 + nex
         ipch <- 0:(np-1)
         k <- floor(sqrt(np))
         dd <- c(-1,1)/2
         rx <- dd + range(ix <- ipch %/% k)
         ry <- dd + range(iy <- 3 + (k-1)- ipch %% k)
         pch <- as.list(ipch) # list with integers & strings
         if(nex > 0) pch[26+ 1:nex] <- as.list(extras)
         plot(rx, ry, type="n", axes = FALSE, xlab = "", ylab = "", main = main)
         abline(v = ix, h = iy, col = "lightgray", lty = "dotted")
         for(i in 1:np) {
           pc <- pch[[i]]
           ## 'col' symbols with a 'bg'-colored interior (where available) :
           points(ix[i], iy[i], pch = pc, col = col, bg = bg, cex = cex)
           if(cextext > 0)
               text(ix[i] - .3, iy[i], pc, col = coltext, cex = cextext)
         }
       }

     pchShow()
     pchShow(c("o","O","0"), cex = 2.5)
     pchShow({}, cex = 4, cextext=0, main=NULL)

