\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,
              nbin = 128,
              bandwidth,
              colramp = colorRampPalette(c("white", brewer.pal(9, "Blues"))),
              nrpoints = 100,
              transformation = function(x) x^.25,
              xlab, ylab, ...) 

     densCols(x, y,
              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 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.
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{...}] 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}}.
\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)

  layout(matrix(1:4, ncol=2, byrow=TRUE))
  smoothScatter(x, nrpoints=0)
  smoothScatter(x)
  smoothScatter(x, nrpoints=Inf, colramp=colorRampPalette(RColorBrewer::brewer.pal(9, "YlOrRd")), bandwidth=40)  

  colors  <- densCols(x)
  plot(x, col=colors, pch=20)
}
\end{ExampleCode}
\end{Examples}

