approxfun               package:stats               R Documentation

Interpolation Functions

Description:

     Return a list of points which linearly interpolate given data
     points, or a function performing the linear (or constant)
     interpolation.

Usage:

     approx   (x, y = NULL, xout, method="linear", n=50,
               yleft, yright, rule = 1, f = 0, ties = mean)

     approxfun(x, y = NULL,       method="linear",
               yleft, yright, rule = 1, f = 0, ties = mean)

Arguments:

    x, y: vectors giving the coordinates of the points to be
          interpolated.  Alternatively a single plotting structure can
          be specified: see 'xy.coords'.

    xout: an optional set of values specifying where interpolation is
          to take place.

  method: specifies the interpolation method to be used.  Choices are
          '"linear"' or '"constant"'.

       n: If 'xout' is not specified, interpolation takes place at 'n'
          equally spaced points spanning the interval ['min(x)',
          'max(x)'].

   yleft: the value to be returned when input 'x' values are less than
          'min(x)'. The default is defined by the value of 'rule' given
          below.

  yright: the value to be returned when input 'x' values are greater
          than 'max(x)'. The default is defined by the value of 'rule'
          given below.

    rule: an integer describing how interpolation is to take place
          outside the interval ['min(x)', 'max(x)']. If 'rule' is '1'
          then 'NA's are returned for such points and if it is '2', the
          value at the closest data extreme is used.

       f: For 'method="constant"' a number between 0 and 1 inclusive,
          indicating a compromise between left- and right-continuous
          step functions. If 'y0' and 'y1' are the values to the left
          and right of the point then the value is 'y0*(1-f)+y1*f' so
          that 'f=0' is right-continuous and 'f=1' is left-continuous.

    ties: Handling of tied 'x' values.  Either a function with a single
          vector argument returning a single number result or the
          string '"ordered"'.

Details:

     The inputs can contain missing values which are deleted, so at
     least two complete '(x, y)' pairs are required (for 'method =
     "linear"', one otherwise).  If there are duplicated (tied) 'x'
     values and 'ties' is a function it is applied to the 'y' values
     for each distinct 'x' value. Useful functions in this context
     include 'mean', 'min', and 'max'.  If 'ties="ordered"' the 'x'
     values are assumed to be already ordered.  The first 'y' value
     will be used for interpolation to the left and the last one for
     interpolation to the right.

Value:

     'approx' returns a list with components 'x' and 'y', containing
     'n' coordinates which interpolate the given data points according
     to the 'method' (and 'rule') desired.

     The function 'approxfun' returns a function performing (linear or
     constant) interpolation of the given data points.  For a given set
     of 'x' values, this function will return the corresponding
     interpolated values.  This is often more useful than 'approx'.

References:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

See Also:

     'spline' and 'splinefun' for spline interpolation.

Examples:

     require(graphics)

     x <- 1:10
     y <- rnorm(10)
     par(mfrow = c(2,1))
     plot(x, y, main = "approx(.) and approxfun(.)")
     points(approx(x, y), col = 2, pch = "*")
     points(approx(x, y, method = "constant"), col = 4, pch = "*")

     f <- approxfun(x, y)
     curve(f(x), 0, 10, col = "green")
     points(x, y)
     is.function(fc <- approxfun(x, y, method = "const")) # TRUE
     curve(fc(x), 0, 10, col = "darkblue", add = TRUE)

     ## Show treatment of 'ties' :

     x <- c(2,2:4,4,4,5,5,7,7,7)
     y <- c(1:6, 5:4, 3:1)
     approx(x,y, xout=x)$y # warning
     (ay <- approx(x,y, xout=x, ties = "ordered")$y)
     stopifnot(ay == c(2,2,3,6,6,6,4,4,1,1,1))
     approx(x,y, xout=x, ties = min)$y
     approx(x,y, xout=x, ties = max)$y

