\HeaderA{xyz.coords}{Extracting Plotting Structures}{xyz.coords}
\keyword{dplot}{xyz.coords}
\begin{Description}\relax
Utility for obtaining consistent x, y and z coordinates and labels
for three dimensional (3D) plots.
\end{Description}
\begin{Usage}
\begin{verbatim}
xyz.coords(x, y = NULL, z = NULL, xlab = NULL, ylab = NULL, zlab = NULL,
           log = NULL, recycle = FALSE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x, y, z}] the x, y and z coordinates of a set of points.
Both \code{y} and \code{z} can be left at \code{NULL}.  In this
case, an attempt is made to interpret \code{x} in a way suitable for
plotting.

If the argument is a formula \code{zvar \textasciitilde{} xvar + yvar},
\code{xvar}, \code{yvar} and \code{zvar} are used as x, y and z
variables;
if the argument is a list containing components \code{x},
\code{y} and \code{z}, these are assumed to define plotting coordinates;
if the argument is a matrix with three columns, the first is
assumed to contain the x values, etc.

Alternatively two arguments \code{x} and \code{y} can be provided
(leaving \code{z = NULL}).  One may be real, the other complex;
in any other case, the arguments are coerced to vectors
and the values plotted against their indices.

\item[\code{xlab, ylab, zlab}] names for the x, y and z variables to be extracted.
\item[\code{log}] character, \code{"x"}, \code{"y"}, \code{"z"} or combinations.
Sets negative values to \code{\LinkA{NA}{NA}} and gives a warning.
\item[\code{recycle}] logical; if \code{TRUE}, recycle (\code{\LinkA{rep}{rep}}) the
shorter ones of \code{x}, \code{y} or \code{z} if their lengths differ.
\end{ldescription}
\end{Arguments}
\begin{Value}
A list with the components
\begin{ldescription}
\item[\code{x}] numeric (i.e., \code{\LinkA{double}{double}}) vector of abscissa values.
\item[\code{y}] numeric vector of the same length as \code{x}.
\item[\code{z}] numeric vector of the same length as \code{x}.
\item[\code{xlab}] \code{character(1)} or \code{NULL}, the axis label of \code{x}.
\item[\code{ylab}] \code{character(1)} or \code{NULL}, the axis label of \code{y}.
\item[\code{zlab}] \code{character(1)} or \code{NULL}, the axis label of \code{z}.
\end{ldescription}
\end{Value}
\begin{Author}\relax
Uwe Ligges and Martin Maechler
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{xy.coords}{xy.coords}} for 2D.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
xyz.coords(data.frame(10*1:9, -4), y = NULL, z = NULL)

xyz.coords(1:6, stats::fft(1:6), z = NULL, xlab = "X", ylab = "Y")

y <- 2 * (x2 <- 10 + (x1 <- 1:10))
xyz.coords(y ~ x1 + x2, y = NULL, z = NULL)

xyz.coords(data.frame(x = -1:9, y = 2:12, z = 3:13), y = NULL, z = NULL,
           log = "xy")
##> Warning message: 2 x values <= 0 omitted ...
\end{ExampleCode}
\end{Examples}

