\HeaderA{level.colors}{A function to compute false colors representing a numeric or
categorical variable}{level.colors}
\keyword{utilities}{level.colors}
\begin{Description}\relax
Calculates false colors from a numeric variable (including factors,
using their numeric codes) given a color scheme and breakpoints.
\end{Description}
\begin{Usage}
\begin{verbatim}
level.colors(x, at, col.regions, colors = TRUE, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] A numeric or \code{\LinkA{factor}{factor}} variable. 
\item[\code{at}] A numeric variable of breakpoints defining intervals along
the range of \code{x}. 
\item[\code{col.regions}] A specification of the colors to be assigned to
each interval defined by \code{at}.  This could be either a vector
of colors, or a function that produces a vector of colors when
called with a single argument giving the number of colors.   See
details below. 
\item[\code{colors}] logical indicating whether colors should be computed
and returned.  If \code{FALSE}, only the indices representing which
interval (among those defined by \code{at}) each value in \code{x}
falls into is returned.  
\item[\code{...}] Extra arguments, ignored. 
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
If \code{at} has length n, then it defines n-1 intervals.  Values of
\code{x} outside the range of \code{at} are not assigned to an
interval, and the return value is \code{NA} for such values.

Colors are chosen by assigning a color to each of the n-1 intervals.
If \code{col.regions} is a palette function (such as
\code{\LinkA{topo.colors}{topo.colors}}, or the result of calling
\code{\LinkA{colorRampPalette}{colorRampPalette}}), it is called with n-1 as an argument
to obtain the colors.  Otherwise, if there are exactly n-1 colors in
\code{col.regions}, these get assigned to the intervals.  If there are
fewer than n-1 colors, \code{col.regions} gets recycled.  If there are
more, a more or less equally spaced (along the length of
\code{col.regions}) subset is chosen.
\end{Details}
\begin{Value}
A vector of the same length as \code{x}.  Depending on the
\code{colors} argument, this could be either a vector of colors (in
a form usable by \R), or a vector of integer indices representing
which interval the values of \code{x} fall in.
\end{Value}
\begin{Author}\relax
Deepayan Sarkar \email{deepayan.sarkar@r-project.org}
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{levelplot}{levelplot}}, \code{\LinkA{colorRampPalette}{colorRampPalette}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}

depth.col <-
    with(quakes, 
         level.colors(depth, at = do.breaks(range(depth), 30),
                      col.regions = terrain.colors))

xyplot(lat ~ long | equal.count(stations), quakes,
       strip = strip.custom(var.name = "Stations"),
       colours = depth.col,
       panel = function(x, y, colours, subscripts, ...) {
           panel.xyplot(x, y, pch = 21, col = "transparent",
                        fill = colours[subscripts], ...)
       })

\end{ExampleCode}
\end{Examples}

