add a convenience function to convert interp output into 3-column matrices

suggested by M. Maechler

DESCRIPTION

 Package: akima
-Version: 0.5-8
-Date: 2012-01-07
+Version: 0.5-9
+Date: 2013-01-19
 Title: Interpolation of irregularly spaced data
 Author: Fortran code by H. Akima
  R port by Albrecht Gebhardt <albrecht.gebhardt@uni-klu.ac.at>
  aspline function by Thomas Petzoldt <thomas.petzoldt@tu-dresden.de>
- enhancements and corrections by Martin Maechler <maechler@stat.math.ethz.ch>
+ interp2xyz, enhancements and corrections by Martin Maechler <maechler@stat.math.ethz.ch>
 Maintainer: Albrecht Gebhardt <albrecht.gebhardt@uni-klu.ac.at>
 Description: Linear or cubic spline interpolation for irregular gridded data
 License: file LICENSE

NAMESPACE

 useDynLib(akima)
-export(aspline,interp,interpp,interp.old,interp.new)
+export(aspline,interp,interpp,interp.old,interp.new,interp2xyz)

R/interp2xyz.R

+##' From an akima() result, produce a 3 column matrix "cbind(x, y, z)"
+##'
+##' @title From interp() Result, Produce 3-column Matrix
+##' @param al a \code{\link{list}} as produced from interp().
+##' @param data.frame logical indicating if result should be data.frame or matrix.
+##' @return a matrix (or data.frame) with three (3) columns, called "x", "y", "z".
+##' @author Martin Maechler, Jan.18, 2013
+interp2xyz <- function(al, data.frame = FALSE) {
+    stopifnot(is.list(al), identical(names(al), c("x","y","z")))
+    xy <- expand.grid(x = al[["x"]], y = al[["y"]], KEEP.OUT.ATTRS=FALSE)
+    cbind(if(!data.frame) data.matrix(xy) else xy,
+          z = as.vector(al[["z"]]))
+}
+

man/interp2xyz.Rd

+\name{interp2xyz}
+\alias{interp2xyz}
+\title{From interp() Result, Produce 3-column Matrix}
+\description{
+  From an \code{\link{interp}()} result, produce a 3-column matrix
+  or \code{\link{data.frame}} \code{cbind(x, y, z)}.
+}
+\usage{
+interp2xyz(al, data.frame = FALSE)
+}
+\arguments{
+  \item{al}{a \code{\link{list}} as produced from \code{\link{interp}()}.}
+  \item{data.frame}{logical indicating if result should be
+    \link{data.frame} or matrix (default).}
+}
+\value{
+  a matrix (or data.frame) with three columns, called
+  \code{"x"}, \code{"y"}, \code{"z"}.
+}
+\author{
+  Martin Maechler, Jan.18, 2013
+}
+\seealso{
+  \code{\link{expand.grid}()} is the \dQuote{essential ingredient} of
+  \code{interp2xyz()}.
+
+  \code{\link{interp}}.
+}
+\examples{
+data(akima)
+ak.spl <- with(akima, interp(x, y, z, linear = FALSE,
+                             xo= seq(0,25, length=100),
+                             yo= seq(0,20, length= 96)))
+str(ak.spl)# list (x[i], y[j], z = <matrix>[i,j])
+
+## Now transform to simple  (x,y,z)  matrix / data.frame :
+str(am <- interp2xyz(ak.spl))
+str(ad <- interp2xyz(ak.spl, data.frame=TRUE))
+## and they are the same:
+stopifnot( am == ad | (is.na(am) & is.na(ad)) )
+}
+\keyword{manip}