splinefun               package:stats               R Documentation

Interpolating Splines

Description:

     Perform cubic (or Hermite) spline interpolation of given data
     points, returning either a list of points obtained by the
     interpolation or a _function_ performing the interpolation.

Usage:

     splinefun(x, y = NULL, method = c("fmm", "periodic", "natural", "monoH.FC"),
               ties = mean)

     spline(x, y = NULL, n = 3*length(x), method = "fmm",
            xmin = min(x), xmax = max(x), xout, ties = mean)

     splinefunH(x, y, m)

Arguments:

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

       m: (for 'splinefunH()'): vector of _slopes_ m[i] at the points
          (x[i],y[i]); these together determine the *H*ermite "spline"
          which is piecewise cubic, (only) _once_ differentiable
          continuously.

  method: specifies the type of spline to be used.  Possible values are
          '"fmm"', '"natural"', '"periodic"' and '"monoH.FC"'.

       n: if 'xout' is left unspecified, interpolation takes place at
          'n' equally spaced points spanning the interval ['xmin',
          'xmax'].

xmin, xmax: left-hand and right-hand endpoint of the interpolation
          interval (when 'xout' is unspecified).

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

    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 one complete '(x, y)' pair is required. If 'method = "fmm"',
     the spline used is that of Forsythe, Malcolm and Moler (an exact
     cubic is fitted through the four points at each end of the data,
     and this is used to determine the end conditions). Natural splines
     are used when 'method = "natural"', and periodic splines when
     'method = "periodic"'.

     The new (R 2.8.0) method '"monoH.FC"' computes a _monotone_
     Hermite spline according to the method of Fritsch and Carlson.  It
     does so by determining slopes such that the Hermite spline,
     determined by (x[i],y[i],m[i]), is monotone (increasing or
     decreasing) *iff* the data are.

     These interpolation splines can also be used for extrapolation,
     that is prediction at points outside the range of 'x'. 
     Extrapolation makes little sense for 'method = "fmm"'; for natural
     splines it is linear using the slope of the interpolating curve at
     the nearest data point.

Value:

     'spline' returns a list containing components 'x' and 'y' which
     give the ordinates where interpolation took place and the
     interpolated values.

     'splinefun' returns a function with formal arguments 'x' and
     'deriv', the latter defaulting to zero.  This function can be used
     to evaluate the interpolating cubic spline ('deriv'=0), or its
     derivatives ('deriv'=1,2,3) at the points 'x', where the spline
     function interpolates the data points originally specified.  This
     is often more useful than 'spline'.

References:

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

     Forsythe, G. E., Malcolm, M. A. and Moler, C. B. (1977) _Computer
     Methods for Mathematical Computations_.

     Fritsch, F. N. and Carlson, R. E. (1980) Monotone piecewise cubic
     interpolation, _SIAM Journal on Numerical Analysis_ *17*, 238-246.

See Also:

     'approx' and 'approxfun' for constant and linear interpolation.

     Package 'splines', especially 'interpSpline' and 'periodicSpline'
     for interpolation splines. That package also generates spline
     bases that can be used for regression splines.

     'smooth.spline' for smoothing splines.

Examples:

     require(graphics)

     op <- par(mfrow = c(2,1), mgp = c(2,.8,0), mar = .1+c(3,3,3,1))
     n <- 9
     x <- 1:n
     y <- rnorm(n)
     plot(x, y, main = paste("spline[fun](.) through", n, "points"))
     lines(spline(x, y))
     lines(spline(x, y, n = 201), col = 2)

     y <- (x-6)^2
     plot(x, y, main = "spline(.) -- 3 methods")
     lines(spline(x, y, n = 201), col = 2)
     lines(spline(x, y, n = 201, method = "natural"), col = 3)
     lines(spline(x, y, n = 201, method = "periodic"), col = 4)
     legend(6,25, c("fmm","natural","periodic"), col=2:4, lty=1)

     y <- sin((x-0.5)*pi)
     f <- splinefun(x, y)
     ls(envir = environment(f))
     splinecoef <- get("z", envir = environment(f))
     curve(f(x), 1, 10, col = "green", lwd = 1.5)
     points(splinecoef, col = "purple", cex = 2)
     curve(f(x, deriv=1), 1, 10, col = 2, lwd = 1.5)
     curve(f(x, deriv=2), 1, 10, col = 2, lwd = 1.5, n = 401)
     curve(f(x, deriv=3), 1, 10, col = 2, lwd = 1.5, n = 401)
     par(op)

     ## Manual spline evaluation --- demo the coefficients :
     .x <- splinecoef$x
     u <- seq(3,6, by = 0.25)
     (ii <- findInterval(u, .x))
     dx <- u - .x[ii]
     f.u <- with(splinecoef,
                 y[ii] + dx*(b[ii] + dx*(c[ii] + dx* d[ii])))
     stopifnot(all.equal(f(u), f.u))

     ## An example with ties (non-unique  x values):
     set.seed(1); x <- round(rnorm(30), 1); y <- sin(pi * x) + rnorm(30)/10
     plot(x,y, main="spline(x,y)  when x has ties")
     lines(spline(x,y, n= 201), col = 2)
     ## visualizes the non-unique ones:
     tx <- table(x); mx <- as.numeric(names(tx[tx > 1]))
     ry <- matrix(unlist(tapply(y, match(x,mx), range, simplify=FALSE)),
                  ncol=2, byrow=TRUE)
     segments(mx, ry[,1], mx, ry[,2], col = "blue", lwd = 2)

     ## An example of  monotone  interpolation
     n <- 20
     set.seed(11)
     x. <- sort(runif(n)) ; y. <- cumsum(abs(rnorm(n)))
     plot(x.,y.)
     curve(splinefun(x.,y.)(x),                add=TRUE, col=2, n=1001)
     curve(splinefun(x.,y., method="mono")(x), add=TRUE, col=3, n=1001)
     legend("topleft", paste("splinefun( \"", c("fmm", "monoH.CS"), "\" )", sep=''),
             col=2:3, lty=1)

