

   PPooiinnttwwiissee BBiivvaarriiaattee IInntteerrppoollaattiioonn ffoorr IIrrrreegguullaarr DDaattaa

        interpp(x, y, z, xo, yo, ncp=0, extrap=F)

   AArrgguummeennttss::

          x: vector of x-coordinates of data points.  Missing
             values are not accepted.

          y: vector of y-coordinates of data points.  Missing
             values are not accepted.

          z: vector of z-coordinates of data points.  Missing
             values are not accepted.

             `x', `y', and `z' must be the same length  and may
             contain no fewer than four points. The points of
             `x' and `y' cannot be collinear, i.e, they cannot
             fall on the same line (two vectors `x' and `y'
             such that `y = ax + b' for some `a', `b' will not
             be accepted).

         xo: vector of x-coordinates of points at which to
             evaluate the interpolating function.

         yo: vector of y-coordinates of points at which to
             evaluate the interpolating function.

        ncp: number of additional points to be used in comput-
             ing partial derivatives at each data point.  `ncp'
             must be either `0' (partial derivatives are not
             used, = linear interpolation), or at least 2 but
             smaller than the number of data points (and
             smaller than 25).

     extrap: logical flag: should extrapolation be used outside
             of the convex hull determined by the data points?

   duplicate: indicates how to handle duplicate data points.
             Possible values are `"error"' - produces an error
             message, `"strip"' - remove duplicate z values,
             `"mean"',`"median"',`"user"'  - calculate  mean ,
             median or user defined function of duplicate z
             values.

     dupfun: this function is applied to duplicate points if
             `duplicate="user"'

   DDeessccrriippttiioonn::

        If `ncp' is zero, linear interpolation is used in the
        triangles bounded by data points.  Cubic interpolation
        is done if partial derivatives are used.  If `extrap'
        is `FALSE', z-values for points outside the convex hull
        are returned as `NA'.  No extrapolation can be per-
        formed if `ncp' is zero.

        The `interpp' function handles duplicate `(x,y)' points
        in different ways. As default it will stop with an
        error message. But it can give duplicate points an
        unique `z' value according to the parameter `duplicate'
        (`mean',`median' or any other user defined function).

        The triangulation scheme used by `interp' works well if
        `x' and `y' have similar scales but will appear
        stretched if they have very different scales.  The
        spreads of `x' and `y' must be within four orders of
        magnitude of each other for `interpp' to work.

   VVaalluuee::

        list with 3 components:

          x: vector of x-coordinates of output points, the same
             as the input argument `xo'.

          y: vector of y-coordinates of output points, the same
             as the input argument `yo'.

          z: fitted z-values.  The value `z[i]' is computed at
             the x,y point `x[i], y[i]'.

   NNOOTTEE::

        Use `interp' if interpolation on a regular grid is
        wanted.

        The two versions  `interpp.old'  and `interpp.new'
        refer to Akimas Fortran code from 1978 and 1996 resp.
        At the moment `interpp.new' does not work porperly (it
        results in a segmentation fault), so it is not used
        from the call wrapper  `interp'.

   RReeffeerreenncceess::

        Akima, H. (1978). A Method of Bivariate Interpolation
        and Smooth Surface Fitting for Irregularly Distributed
        Data Points.  ACM Transactions on Mathematical Soft-
        ware, 4, 148-164.

        Akima, H. (1996). Algorithm 761: scattered-data surface
        fitting that has the accuracy of a cubic polynomial.
        ACM Transactions on Mathematical Software, 22, 362-371.

   SSeeee AAllssoo::

        `contour', `image', `approx', `spline', `outer',
        `expand.grid',`interp'.

   EExxaammpplleess::

        data(akima)
        # linear interpolation at points (1,2), (5,6) and (10,12)
        akima.lip<-interpp(akima$x, akima$y, akima$z,c(1,5,10),c(2,6,12))

