\HeaderA{levelplot}{Level plots and contour plots}{levelplot}
\aliasA{contourplot}{levelplot}{contourplot}
\methaliasA{contourplot.array}{levelplot}{contourplot.array}
\methaliasA{contourplot.formula}{levelplot}{contourplot.formula}
\methaliasA{contourplot.matrix}{levelplot}{contourplot.matrix}
\methaliasA{contourplot.table}{levelplot}{contourplot.table}
\methaliasA{levelplot.array}{levelplot}{levelplot.array}
\methaliasA{levelplot.formula}{levelplot}{levelplot.formula}
\methaliasA{levelplot.matrix}{levelplot}{levelplot.matrix}
\methaliasA{levelplot.table}{levelplot}{levelplot.table}
\keyword{hplot}{levelplot}
\begin{Description}\relax
Draw Level Plots and Contour plots.
\end{Description}
\begin{Usage}
\begin{verbatim}
levelplot(x, data, ...)
contourplot(x, data, ...)

## S3 method for class 'formula':
levelplot(x,
          data,
          allow.multiple = is.null(groups) || outer,
          outer = TRUE,
          aspect = "fill",
          panel = lattice.getOption("panel.levelplot"),
          prepanel = NULL,
          scales = list(),
          strip = TRUE,
          groups = NULL,
          xlab,
          xlim,
          ylab,
          ylim,
          at,
          cuts = 15,
          pretty = FALSE,
          region = TRUE,
          drop.unused.levels = lattice.getOption("drop.unused.levels"),
          ...,
          lattice.options = NULL,
          default.scales = list(),
          colorkey = region,
          col.regions,
          alpha.regions,
          subset = TRUE)

## S3 method for class 'formula':
contourplot(x,
            data,
            panel = lattice.getOption("panel.contourplot"),
            cuts = 7,
            labels = TRUE,
            contour = TRUE,
            pretty = TRUE,
            region = FALSE,
            ...)

## S3 method for class 'table':
levelplot(x, data = NULL, aspect = "iso", ..., xlim, ylim)

## S3 method for class 'table':
contourplot(x, data = NULL, aspect = "iso", ..., xlim, ylim)

## S3 method for class 'matrix':
levelplot(x, data = NULL, aspect = "iso",
          ..., xlim, ylim,
          row.values = seq_len(nrow(x)),
          column.values = seq_len(ncol(x)))

## S3 method for class 'matrix':
contourplot(x, data = NULL, aspect = "iso",
            ..., xlim, ylim,
            row.values = seq_len(nrow(x)),
            column.values = seq_len(ncol(x)))

## S3 method for class 'array':
levelplot(x, data = NULL, ...)

## S3 method for class 'array':
contourplot(x, data = NULL, ...)

\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] for the \code{formula} method, a formula of the form \code{z \textasciitilde{} x * y
      | g1 * g2 * ...}, where \code{z} is a numeric response, and
\code{x}, \code{y} are numeric values evaluated on a rectangular
grid.  \code{g1, g2, ...} are optional conditional variables, and
must be either factors or shingles if present.

Calculations are based on the assumption that all x and y values are
evaluated on a grid (defined by their unique values). The function
will not return an error if this is not true, but the display might
not be meaningful.  However, the x and y values need not be equally
spaced.

Both \code{levelplot} and \code{wireframe} have methods for
\code{matrix}, \code{array}, and \code{table} objects, in which case
\code{x} provides the \code{z} vector described above, while its
rows and columns are interpreted as the \code{x} and \code{y}
vectors respectively.  This is similar to the form used in
\code{filled.contour} and \code{image}.  For higher-dimensional
arrays and tables, further dimensions are used as conditioning
variables.  Note that the dimnames may be duplicated; this is
handled by calling \code{\LinkA{make.unique}{make.unique}} to make the names
unique (although the original labels are used for the x- and
y-axes).

\item[\code{data}] For the \code{formula} methods, an optional data frame in which
variables in the formula (as well as \code{groups} and
\code{subset}, if any) are to be evaluated.  Usually ignored with a
warning in other cases.

\item[\code{row.values, column.values}] Optional vectors of values that
define the grid when \code{x} is a matrix.  \code{row.values} and
\code{column.values} must have the same lengths as \code{nrow(x)}
and \code{ncol(x)} respectively.  By default, row and column
numbers. 
\item[\code{panel}] panel function used to create the display, as described in
\code{\LinkA{xyplot}{xyplot}}

\item[\code{aspect}] For the \code{matrix} methods, the default aspect ratio is chosen to
make each cell square.  The usual default is \code{aspect="fill"},
as described in \code{\LinkA{xyplot}{xyplot}}.

\item[\code{at}] numeric vector giving breakpoints along the range of
\code{z}. Contours (if any) will be drawn at these heights, and the
regions in between would be colored using \code{col.regions}.  In
the latter case, values outside the range of \code{at} will not be
drawn at all.  This serves as a way to limit the range of the data
shown, similar to what a \code{zlim} argument might have been used
for.  However, this also means that when supplying \code{at}
explicitly, one has to be careful to include values outside the
range of \code{z} to ensure that all the data are shown.

\item[\code{col.regions}] color vector to be used if regions is TRUE. The
general idea is that this should be a color vector of moderately
large length (longer than the number of regions. By default this is
100). It is expected that this vector would be gradually varying in
color (so that nearby colors would be similar). When the colors are
actually chosen, they are chosen to be equally spaced along this
vector.  When there are more regions than colors in
\code{col.regions}, the colors are recycled.  The actual color
assignment is performed by \code{\LinkA{level.colors}{level.colors}}, which is
documented separately.

\item[\code{alpha.regions}] numeric, specifying alpha transparency (works only on some devices)

\item[\code{colorkey}] logical specifying whether a color key is to be drawn
alongside the plot, or a list describing the color key. The list may
contain the following components:

\describe{

\item[\code{space}:] location of the colorkey, can be one of \code{"left"},
\code{"right"}, \code{"top"} and \code{"bottom"}.  Defaults to
\code{"right"}.


\item[\code{x}, \code{y}:] location, currently unused 

\item[\code{col}:] vector of colors 

\item[\code{at}:] numeric vector specifying where the colors change. must be of
length 1 more than the col vector.


\item[\code{labels}:] a character vector for labelling the \code{at} values, or more
commonly, a list describing characteristics of the labels.  This
list may include components \code{labels}, \code{at},
\code{cex}, \code{col}, \code{rot}, \code{font}, \code{fontface}
and \code{fontfamily}.


\item[\code{tick.number}:] approximate number of ticks. 

\item[\code{corner}:] interacts with x, y; unimplemented 

\item[\code{width}:] width of the key 

\item[\code{height}:] length of key w.r.t side of plot. 
}

\item[\code{contour}] logical, whether to draw contour lines.

\item[\code{cuts}] number of levels the range of \code{z} would be divided into

\item[\code{labels}] typically a logical indicating whether contour lines should be
labelled, but other possibilities for more sophisticated control
exists.  Details are documented in the help page for
\code{\LinkA{panel.levelplot}{panel.levelplot}}, to which this argument is passed on
unchanged.  That help page also documents the \code{label.style}
argument, which affects how the labels are rendered.

\item[\code{pretty}] logical, whether to use pretty cut locations and labels

\item[\code{region}] logical, whether regions between contour lines should be filled

\item[\code{allow.multiple, outer, prepanel, scales, strip, groups, xlab,
xlim, ylab, ylim, drop.unused.levels, lattice.options,
default.scales, subset}] these arguments are described in the help page for
\code{\LinkA{xyplot}{xyplot}}.

\item[\code{...}] other arguments.  Some are processed by \code{levelplot}
or \code{contourplot}, and those unrecognized are passed on to the
panel function.  
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
These and all other high level Trellis functions have several
arguments in common. These are extensively documented only in the
help page for \code{xyplot}, which should be consulted to learn more
detailed usage.

Other useful arguments are mentioned in the help page for the default
panel function \code{\LinkA{panel.levelplot}{panel.levelplot}} (these are formally
arguments to the panel function, but can be specified in the high
level calls directly).
\end{Details}
\begin{Value}
An object of class \code{"trellis"}. The
\code{\LinkA{update}{update}} method can be used to
update components of the object and the
\code{\LinkA{print}{print}} method (usually called by
default) will plot it on an appropriate plotting device.
\end{Value}
\begin{Author}\relax
Deepayan Sarkar \email{Deepayan.Sarkar@R-project.org}
\end{Author}
\begin{References}\relax
Sarkar, Deepayan (2008) "Lattice: Multivariate Data Visualization with
R", Springer. \url{http://lmdvr.r-forge.r-project.org/}
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{xyplot}{xyplot}}, \code{\LinkA{Lattice}{Lattice}},
\code{\LinkA{panel.levelplot}{panel.levelplot}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
x <- seq(pi/4, 5 * pi, length.out = 100)
y <- seq(pi/4, 5 * pi, length.out = 100)
r <- as.vector(sqrt(outer(x^2, y^2, "+")))
grid <- expand.grid(x=x, y=y)
grid$z <- cos(r^2) * exp(-r/(pi^3))
levelplot(z~x*y, grid, cuts = 50, scales=list(log="e"), xlab="",
          ylab="", main="Weird Function", sub="with log scales",
          colorkey = FALSE, region = TRUE)

#S-PLUS example
require(stats)
attach(environmental)
ozo.m <- loess((ozone^(1/3)) ~ wind * temperature * radiation,
       parametric = c("radiation", "wind"), span = 1, degree = 2)
w.marginal <- seq(min(wind), max(wind), length.out = 50)
t.marginal <- seq(min(temperature), max(temperature), length.out = 50)
r.marginal <- seq(min(radiation), max(radiation), length.out = 4)
wtr.marginal <- list(wind = w.marginal, temperature = t.marginal,
        radiation = r.marginal)
grid <- expand.grid(wtr.marginal)
grid[, "fit"] <- c(predict(ozo.m, grid))
contourplot(fit ~ wind * temperature | radiation, data = grid,
            cuts = 10, region = TRUE,
            xlab = "Wind Speed (mph)",
            ylab = "Temperature (F)",
            main = "Cube Root Ozone (cube root ppb)")
detach()
\end{ExampleCode}
\end{Examples}

