interp                 package:akima                 R Documentation

_G_r_i_d_d_e_d _B_i_v_a_r_i_a_t_e _I_n_t_e_r_p_o_l_a_t_i_o_n _f_o_r _I_r_r_e_g_u_l_a_r _D_a_t_a

_D_e_s_c_r_i_p_t_i_o_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 performed if 'ncp' is zero.

     The 'interp' 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 'interp' to work.

_U_s_a_g_e:

     interp(x, y, z, xo=<<see below>>, yo=<<see below>>, ncp=0, extrap=FALSE, duplicate = "error", dupfun = NULL)
     interp.old(x, y, z, xo=<<see below>>, yo=<<see below>>, ncp=0, extrap=FALSE, duplicate = "error", dupfun = NULL)
     interp.new(x, y, z, xo=<<see below>>, yo=<<see below>>, linear=FALSE, ncp=NULL, extrap=FALSE, duplicate = "error", dupfun = NULL)

_A_r_g_u_m_e_n_t_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). 'interp' is meant for cases in which
          you have 'x', 'y' values scattered over a plane and a 'z'
          value for each.  If, instead, you are trying to evaluate a
          mathematical function, or get a graphical interpretation of
          relationships that can be described by a polynomial, try
          'outer()'.          

      xo: vector of x-coordinates of output grid.  The default is 40
          points evenly spaced over the range of 'x'.  If extrapolation
          is not being used ('extrap=FALSE', the default), 'xo' should
          have a range that is close to or inside of the range of 'x'
          for the results to be meaningful. 

      yo: vector of y-coordinates of output grid.  The default is 40
          points evenly spaced over the range of 'y'.  If extrapolation
          is not being used ('extrap=FALSE', the default), 'yo' should
          have a range that is close to or inside of the range of 'y'
          for the results to be meaningful. 

  linear: logical, switch to linear interpolation in 'interp.new'

     ncp: number of additional points to be used in computing partial
          derivatives at each data point.   'ncp' must be either '0'
          (partial derivatives are not used), or at least 2 but smaller
          than the number of data points (and smaller than 25). This
          option is only supported by 'interp.old'. 

  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"'          

_V_a_l_u_e:

     list with 3 components:

       x: vector of x-coordinates of output grid, the same as the input
          argument 'xo', if present.  Otherwise, a vector 40 points
          evenly spaced over the range of the input 'x'. 

       y: vector of y-coordinates of output grid, the same as the input
          argument 'yo', if present.  Otherwise, a vector 40 points
          evenly spaced over the range of the input 'x'. 

       z: matrix of fitted z-values.  The value 'z[i,j]' is computed at
          the x,y point 'x[i], y[j]'. 'z' has dimensions 'length(x)'
          times 'length(y)' ('length(xo)' times 'length(yo)').

_N_o_t_e:

     'interp' is a wrapper for the two versions 'interp.old' (it uses
     (almost) the same Fortran code from Akima 1978 as the S-Plus
     version) and 'interp.new' (it is based on new Fortran code from
     Akima 1996). For linear interpolation the old version is choosen,
     but spline interpolation is done by the new version.

     At the moment 'interp.new' ignores 'ncp' and does only bicubic
     spline interpolation.

     The resulting structure is suitable for input to the functions
     'contour' and 'image'.  Check the requirements of these functions
     when choosing values  for 'xo' and 'yo'.

_R_e_f_e_r_e_n_c_e_s:

     Akima, H. (1978). A Method of Bivariate Interpolation and Smooth
     Surface Fitting for Irregularly Distributed Data Points. ACM
     Transactions on Mathematical Software, *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_e_e _A_l_s_o:

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

_E_x_a_m_p_l_e_s:

     data(akima)
     # linear interpolation
     akima.li <- interp(akima$x, akima$y, akima$z)
     image(akima.li$x,akima.li$y,akima.li$z)
     contour(akima.li$x,akima.li$y,akima.li$z,add=TRUE)
     points(akima$x,akima$y)

     # increase smoothness
     akima.smooth <- interp(akima$x, akima$y, akima$z,
           xo=seq(0,25, length=100),  yo=seq(0,20, length=100))
     image(akima.smooth$x,akima.smooth$y,akima.smooth$z)
     contour(akima.smooth$x,akima.smooth$y,akima.smooth$z,add=TRUE)
     points(akima$x,akima$y)
     # use triangulation library to
     # show underlying triangulation:
     if(library(tripack, logical.return=TRUE))
       plot(tri.mesh(akima),add=TRUE,lty="dashed")

     # use only 15 points (interpolation only within convex hull!)
     akima.part <- interp(akima$x[1:15],akima$y[1:15],akima$z[1:15])
     image(akima.part$x,akima.part$y,akima.part$z)
     contour(akima.part$x,akima.part$y,akima.part$z,add=TRUE)
     points(akima$x[1:15],akima$y[1:15])

     # spline interpolation, use 5 points to calculate derivatives
     # interp gives `linear interpolation not yet implemented with interp.new()'
     akima.spl <- interp.old(akima$x, akima$y, akima$z,
           xo=seq(0,25, length=100),  yo=seq(0,20, length=100),ncp=5)
     image(akima.spl$x,akima.spl$y,akima.spl$z)
     contour(akima.spl$x,akima.spl$y,akima.spl$z,add=TRUE)
     points(akima$x,akima$y)

     # example with duplicate points
     data(airquality)
     air <- airquality[(!is.na(airquality$Temp) & 
                        !is.na(airquality$Ozone) & 
                        !is.na(airquality$Solar.R)),]
     # gives an error:
     ## Don't run: air.ip <- interp(air$Temp,air$Solar.R,air$Ozone)
     # use mean of duplicate points:
     air.ip <- interp(air$Temp,air$Solar.R,air$Ozone,duplicate="mean")

