\Header{points}{Add Points to a Plot}
\methalias{points.default}{points}
\keyword{aplot}{points}
\begin{Description}\relax
\code{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.\end{Description}
\begin{Usage}
\begin{verbatim}
points(x, ...)
points.default(x, y=NULL, type="p", pch=par("pch"), col=par("col"),
               bg=NA, cex=1, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x, y}] coordinate vectors of points to plot.
\item[\code{type}] character indicating the type of plotting; actually any of
the \code{type}s as in \code{\Link{plot}}.
\item[\code{pch}] plotting ``character'', i.e. symbol to use.  \code{pch} can
either be a \code{\Link{character}} or an integer code for a set of
graphics symbols.  The full set of S symbols is available with
\code{pch=0:18}, see the last picture from \code{example(points)},
i.e., the examples below.

In addition, there is a special set of \R{} plotting symbols which
can be obtained with \code{pch=19:25} and \code{21:25} can be
colored and filled with different colors:
\Itemize{
\item \code{pch=19}: solid circle,
\item \code{pch=20}: bullet (smaller circle),
\item \code{pch=21}: circle,
\item \code{pch=22}: square,
\item \code{pch=23}: diamond,
\item \code{pch=24}: triangle point-up,
\item \code{pch=25}: triangle point down.
}

\item[\code{col}] color code or name, see \code{\Link{colors}},
\code{\Link{palette}}.
\item[\code{bg}] background (``fill'') color for open plot symbols
\item[\code{cex}] character expansion
\item[\code{...}] Further graphical parameters (see \code{\Link{plot.xy}}
and \code{\Link{par}}) may also be supplied as arguments.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The coordinates can be passed in a plotting structure
(a list with \code{x} and \code{y} components), a two-column matrix, a
time series, \dots.  See \code{\Link{xy.coords}}.

Graphical parameters are permitted as arguments to this function.\end{Details}
\begin{SeeAlso}\relax
\code{\Link{plot}}, \code{\Link{lines}}, and the underlying
``primitive'' \code{\Link{plot.xy}}.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
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)
}
\end{ExampleCode}
\end{Examples}

