\Header{coplot}{Conditioning Plots}
\alias{co.intervals}{coplot}
\keyword{hplot}{coplot}
\keyword{aplot}{coplot}
\begin{Usage}
\begin{verbatim}
coplot(formula, data, given.values, panel = points, rows, columns,
       show.given = TRUE, col = par("fg"), pch = par("pch"),
       xlab = paste("Given :", a.name),
       ylab = paste("Given :", b.name),
       number = 6, overlap = 0.5, ...)
co.intervals(x, number = 6, overlap = 0.5)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\texttt{formula}] a formula describing the form of conditioning plot.  A
formula of the form \texttt{y $\,\tilde{\,}$ x | a} indicates that plots of
\texttt{y} versus \texttt{x} should be produced conditional on the
variable \texttt{a}.  A formula of the form \texttt{y $\,\tilde{\,}$ x| a * b}
indicates that plots of \texttt{y} versus \texttt{x} should be produced
conditional on the two variables \texttt{a} and \texttt{b}.

\texttt{x} and \texttt{y} must be numeric, but \texttt{a} and \texttt{b} may
be either numeric or factors.
\item[\texttt{data}] a data frame containing values for any variables in the
formula.  By default the environment where \texttt{coplot} was called
from is used.
\item[\texttt{given.values}] a value or list of two values which determine how
the conditioning on \texttt{a} and \texttt{b} is to take place.

When there is no \texttt{b} (i.e., conditioning only on \texttt{a}),
usually this is a matrix with two columns each row of which gives an
interval, to be conditioned on, but is can also be a single vector
of numbers or a set of factor levels (if the variable being
conditioned on is a factor). In this case (no \texttt{b}),
the result of \texttt{co.intervals(..)} can be used directly as
\texttt{given.values} argument.

\item[\texttt{panel}] a \texttt{\Link{function}(x,y, col, pch, ...)}
which gives the action to be carried out in
each panel of the display.  The default is \texttt{points}.
\item[\texttt{rows}] the panels of the plot are laid out in a \texttt{rows} by
\texttt{columns} array.  \texttt{rows} gives the number of rows in the
array.
\item[\texttt{columns}] the number of columns in the panel layout array.
\item[\texttt{show.given}] logical (possibly of length 2 for 2 conditioning
variables): should conditioning plots be shown for the
corresponding conditioning variables (default \texttt{TRUE})
\item[\texttt{col}] a vector of colors to be used to plot the points.  If too
short, the values are recycled.
\item[\texttt{pch}] a vector of plotting symbols or characters.  If too short,
the values are recycyled.
\item[\texttt{xlab}] character; label to use for the 1st conditioning variable.
\item[\texttt{ylab}] character; label to use for the 2nd conditioning variable.
\item[\texttt{number}] integer; the number of conditioning intervals,
possibly of length 2 for x and y direction.
\item[\texttt{overlap}] numeric < 1; the fraction of overlap of the
conditioning variables, possibly of length 2 for x and y
direction.  When overlap < 0, there will be \emph{gaps} between
the data slices.
\item[\texttt{...}] additional arguments to the panel function.
\end{ldescription}
\end{Arguments}
\begin{Description}
This function produces two variants of the conditioning plots
discussed in the reference below.\end{Description}
\begin{Value}
\texttt{co.intervals(., number, .)} returns a (\texttt{number} \eqn{\times}{x}
2) \texttt{\Link{matrix}}, say \texttt{ci},  where \texttt{ci[k,]} is
the \texttt{\Link{range}} of \texttt{x} values for the \texttt{k}-th interval.\end{Value}
\begin{References}
Cleveland, W. S. (1993).
\emph{Visualizing Data}.
New Jersey: Summit Press.\end{References}
\begin{SeeAlso}
\texttt{\Link{pairs}},
\texttt{\Link{panel.smooth}},
\texttt{\Link{points}}.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## Tonga Trench Earthquakes
data(quakes)
coplot(long ~ lat | depth, data = quakes)
given.depth <- co.intervals(quakes$depth, number=4, overlap=.1)
coplot(long ~ lat | depth, data = quakes, given.values=given.depth)

## Conditioning on 2 variables:
ll.dm <- long ~ lat | depth * mag
coplot(ll.dm, data = quakes)
coplot(ll.dm, data = quakes, number=c(4,7), show.given = c(T,F))
coplot(ll.dm, data = quakes, number=c(3,7),
       overlap=c(-.5,.1)) # negative overlap DROPS values

data(warpbreaks)
## given two factors
coplot(breaks ~ 1:54 | wool * tension, data = warpbreaks, col = 'red')

## Example with empty panels:
data(state)
attach(data.frame(state.x77))#> don't need `data' arg. below
coplot(Life.Exp ~ Income | Illiteracy * state.region, number = 3,
       panel=function(x,y,...) panel.smooth(x,y, span= .8, ...))
\end{ExampleCode}
\end{Examples}

