\HeaderA{smoothScatter}{Scatterplots with Smoothed Densities Color Representation}{smoothScatter}
\keyword{hplot}{smoothScatter}
\begin{Description}\relax
\code{smoothScatter} produces a smoothed color density
representation of the scatterplot, obtained through a kernel
density estimate. \code{densCols} produces a vector containing
colors which encode the local densities at each point in a
scatterplot.
\end{Description}
\begin{Usage}
\begin{verbatim}
smoothScatter(x, y = NULL, nbin = 128, bandwidth,
              colramp = colorRampPalette(c("white", blues9)),
              nrpoints = 100, pch = ".", cex = 1, col = "black",
              transformation = function(x) x^.25,
              postPlotHook = box,
              xlab = NULL, ylab = NULL, xlim, ylim,
              xaxs = par("xaxs"), yaxs = par("yaxs"), ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x, y}] the \code{x} and \code{y} arguments provide the x and y
coordinates for the plot.  Any reasonable way of defining the
coordinates is acceptable.  See the function \code{\LinkA{xy.coords}{xy.coords}}
for details.  If supplied separately, they must be of the same length.
\item[\code{nbin}] numeric vector of length one (for both directions) or two
(for x and y separately) specifying the number of equally spaced
grid points for the density estimation; directly used as
\code{gridsize} in \code{\LinkA{bkde2D}{bkde2D}()}.
\item[\code{bandwidth}] numeric vector (length 1 or 2) of smoothing bandwidth(s).
If missing, a more or less useful default is used. \code{bandwidth}
is subsequently passed to function
\code{\LinkA{bkde2D}{bkde2D}}.
\item[\code{colramp}] function accepting an integer \code{n} as an argument and
returning \code{n} colors.
\item[\code{nrpoints}] number of points to be superimposed on the density
image.  The first \code{nrpoints} points from those areas of lowest
regional densities will be plotted.  Adding points to the plot
allows for the identification of outliers.  If all points are to be
plotted, choose \code{nrpoints = Inf}.
\item[\code{pch, cex, col}] arguments passed to \code{\LinkA{points}{points}},
when \code{nrpoints > 0}: point symbol, character expansion factor
and color, see also \code{\LinkA{par}{par}}.
\item[\code{transformation}] function mapping the density scale to the color scale.
\item[\code{postPlotHook}] either \code{NULL} or a function which will be
called (with no arguments) after \code{\LinkA{image}{image}}.
\item[\code{xlab, ylab}] character strings to be used as axis labels, passed
to \code{\LinkA{image}{image}}.
\item[\code{xlim, ylim}] numeric vectors of length 2 specifying axis limits.
\item[\code{xaxs, yaxs, ...}] further arguments, passed to \code{\LinkA{image}{image}}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{smoothScatter} produces a smoothed version of a scatter plot.
Two dimensional (kernel density) smoothing is performed by
\code{\LinkA{bkde2D}{bkde2D}} from package \pkg{KernSmooth}.
See the examples for how to use this function together with
\code{\LinkA{pairs}{pairs}}.
\end{Details}
\begin{Author}\relax
Florian Hahne at FHCRC, originally
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{bkde2D}{bkde2D}}
from package \pkg{KernSmooth};
\code{\LinkA{densCols}{densCols}} which uses the same smoothing
computations and \code{\LinkA{blues9}{blues9}} in package
\pkg{grDevices}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  ## A largish data set
  n <- 10000
  x1  <- matrix(rnorm(n), ncol=2)
  x2  <- matrix(rnorm(n, mean=3, sd=1.5), ncol=2)
  x   <- rbind(x1,x2)

  oldpar <- par(mfrow=c(2,2))
  smoothScatter(x, nrpoints=0)
  smoothScatter(x)

  ## a different color scheme:
  Lab.palette <- colorRampPalette(c("blue", "orange", "red"), space = "Lab")
  smoothScatter(x, colramp = Lab.palette)

  ## somewhat similar, using identical smoothing computations,
  ## but considerably *less* efficient for really large data:
  plot(x, col = densCols(x), pch=20)

  ## use with pairs:
  par(mfrow=c(1,1))
  y <- matrix(rnorm(40000), ncol=4) + 3*rnorm(10000)
  y[, c(2,4)] <-  -y[, c(2,4)]
  pairs(y, panel=function(...) {par(new=TRUE);smoothScatter(..., nrpoints=0)})

  par(oldpar)
\end{ExampleCode}
\end{Examples}

