\HeaderA{smoothScatter}{Scatterplots with smoothed densities color representation}{smoothScatter}
\aliasA{densCols}{smoothScatter}{densCols}
\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", brewer.pal(9, "Blues"))),
              nrpoints=100,
              transformation=function(x) x^.25,
              xlab=NULL, ylab=NULL, postPlotHook=box, pch=".", cex=1, ...) 

     densCols(x, y=NULL,
              nbin=128,
              bandwidth,
              colramp=colorRampPalette(brewer.pal(9, "Blues")[-(1:3)]))
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] Numeric vector containing x-values or n by 2 matrix containing x
and y values.
\item[\code{y}] Numeric vector containing y-values (optional). The length of \code{x}
must be the same as that of \code{y}.
\item[\code{nbin}] Numeric vector of length 1 (for both directions) or
2 (for x and y separately) containing the number of equally spaced
grid points for the density estimation.
\item[\code{bandwidth}] Numeric vector: the smoothing bandwidth. If missing,
these functions come up with a more or less useful guess. This
parameter then gets passed on to the 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}] Numeric vector of length 1 giving 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{transformation}] Function that maps the density scale to the color scale.
\item[\code{xlab}] Character. Gets passed on to \code{\LinkA{image}{image}}
\item[\code{ylab}] Character. Gets passed on to \code{\LinkA{image}{image}}
\item[\code{postPlotHook}] Either \code{NULL} or a function with no
arguments that will be called after \code{\LinkA{image}{image}}.
\item[\code{pch}] \code{\LinkA{points}{points}} parameter setting
\item[\code{cex}] character expansion parameter setting
(see \code{\LinkA{par}{par}}) passed to the \code{\LinkA{points}{points}} phase
of the function
\item[\code{...}] Further arguments that are passed on to \code{\LinkA{image}{image}}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
These functions are convenience wrappers around
\code{\LinkA{bkde2D}{bkde2D}}.

The treatment of the \code{x} and \code{y} arguments attempts to be
consistent with that e.g. of \code{\LinkA{plot.default}{plot.default}}.

See examples for how to use this function together withn \code{\LinkA{pairs}{pairs}}.
\end{Details}
\begin{Value}
\code{smoothScatter} is called for its side-effect, producing a
plot on the current graphics device. \code{densCols} returns
a vector of length \code{nrow(x)} that contains colors to be used
in a subsequent scatterplot. Each color represents the local density
around the corresponding point.
\end{Value}
\begin{Author}\relax
Florian Hahne <f.hahne@dkfz.de>
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{bkde2D}{bkde2D}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
if(interactive()) {
  x1  <- matrix(rnorm(1e4), ncol=2)
  x2  <- matrix(rnorm(1e4, mean=3, sd=1.5), ncol=2)
  x   <- rbind(x1,x2)

  oldpar <- par(mfrow=c(2,2))
  smoothScatter(x, nrpoints=0)
  smoothScatter(x)
  smoothScatter(x,nrpoints=Inf,colramp=colorRampPalette(RColorBrewer::brewer.pal(9, "YlOrRd")),bandwidth=1)  

  colors  <- densCols(x)
  plot(x, col=colors, 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}