# R: Add Points to a Plot

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

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

[Package graphics version 2.6.0 Index]