\Header{filled.contour}{Level (Contour) Plots}
\keyword{hplot}{filled.contour}
\keyword{aplot}{filled.contour}
\begin{Description}\relax
This function produces a contour plot with the areas between
the contours filled in solid color (Cleveland calls this a
level plot).  A key showing how the colors map to z values
is shown to the right of the plot.\end{Description}
\begin{Usage}
\begin{verbatim}
filled.contour(x = seq(0, 1, len = nrow(z)),
               y = seq(0, 1, len = ncol(z)),
               z,
               xlim = range(x, finite=TRUE),
               ylim = range(y, finite=TRUE),
               zlim = range(z, finite=TRUE),
               levels = pretty(zlim, nlevels), nlevels = 20,
               color.palette = cm.colors,
               col = color.palette(length(levels) - 1),
               plot.title, plot.axes, key.title, key.axes,
               asp = NA, xaxs = "i", yaxs = "i", las = 1, axes = TRUE,
               ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x,y}] locations of grid lines at which the values in \code{z} are
measured.  These must be in ascending order.  By default, equally 
spaced values from 0 to 1 are used.  If \code{x} is a \code{list},
its components \code{x\$x} and \code{x\$y} are used for \code{x}
and \code{y}, respectively. If the list has component \code{z} this
is used for \code{z}.
\item[\code{z}] a matrix containing the values to be plotted (\code{NA}s are
allowed).  Note that \code{x} can be used instead of \code{z} for  
convenience.
\item[\code{xlim}] x limits for the plot.
\item[\code{ylim}] y limits for the plot.
\item[\code{zlim}] z limits for the plot.
\item[\code{levels}] a set of levels which are used to partition the range
of \code{z}.  Must be \bold{strictly} increasing (and finite).  Areas
with \code{z} values between consecutive levels are painted with the
same color.
\item[\code{nlevels}] if \code{levels} is not specified, the range of \code{z},
values is divided into approximately this many levels.
\item[\code{color.palette}] a color palette function to be used to assign
colors in the plot.
\item[\code{col}] an explicit set of colors to be used in the plot.
This argument overrides any palette function specification.
\item[\code{plot.title}] statements which add titles the main plot.
\item[\code{plot.axes}] statements which draw axes on the main plot.
This overrides the default axes.
\item[\code{key.title}] statements which add titles for the plot key.
\item[\code{key.axes}] statements which draw axes on the plot key.
This overrides the default axis.
\item[\code{asp}] the \eqn{y/x}{} aspect ratio, see \code{\Link{plot.window}}.
\item[\code{xaxs}] the x axis style.  The default is to use internal
labeling.
\item[\code{yaxs}] the y axis style.  The default is to use internal
labeling.
\item[\code{las}] the style of labeling to be used.  The default is to
use horizontal labeling. 
\item[\code{axes, ...}] additional graphical parameters.
\end{ldescription}
\end{Arguments}
\begin{Note}\relax
This function currently uses the \code{layout} function and so
is restricted to a full page display.  In future it is likely to
be replaced by a genuine \code{levelplot} function which will
work in multipanel displays.

The ouput produced by \code{filled.contour} is actually a combination
of two plots; one is the filled contour and one is the legend.
Two separate coordinate systems are set up for these
two plots, but they are only used internally - once the function has
returned these coordinate systems are lost.  If you
want to annotate the main contour plot, for example to add points,
you can specify
graphics commands in the plot.axes argument.  An example is given
below.\end{Note}
\begin{Author}\relax
Ross Ihaka.\end{Author}
\begin{References}\relax
Cleveland, W. S. (1993)
\emph{Visualizing Data}.
Summit, New Jersey: Hobart.\end{References}
\begin{SeeAlso}\relax
\code{\Link{contour}}, \code{\Link{image}}, \code{\Link{palette}}.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
data(volcano)
filled.contour(volcano, color = terrain.colors, asp = 1)# simple

x <- 10*1:nrow(volcano)
y <- 10*1:ncol(volcano)
filled.contour(x, y, volcano, color = terrain.colors,
    plot.title = title(main = "The Topography of Maunga Whau",
    xlab = "Meters North", ylab = "Meters West"),
    plot.axes = { axis(1, seq(100, 800, by = 100))
                  axis(2, seq(100, 600, by = 100)) },
    key.title = title(main="Height\n(meters)"),
    key.axes = axis(4, seq(90, 190, by = 10)))# maybe also asp=1
mtext(paste("filled.contour(.) from", R.version.string),
      side = 1, line = 4, adj = 1, cex = .66)

# Annotating a filled contour plot
a <- expand.grid(1:20, 1:20)
b <- matrix(a[,1] + a[,2], 20)
filled.contour(x = 1:20, y = 1:20, z = b,
               plot.axes={ axis(1); axis(2); points(10,10) })
\end{ExampleCode}
\end{Examples}

