smooth.spline             package:modreg             R Documentation

Fit a Smoothing Spline

Description:

     Fits a cubic smoothing spline to the supplied data.

Usage:

     smooth.spline(x, y, w = rep(1, length(x)), df = 5, spar = NULL,
                   cv = FALSE, all.knots = FALSE, df.offset = 0, penalty = 1,
                   control.spar = list())

Arguments:

       x: a vector giving the values of the predictor variable, or  a
          list or a two-column matrix specifying x and y. 

       y: responses. If `y' is missing, the responses are assumed to be
          specified by `x'.

       w: optional vector of weights

      df: the desired equivalent number of degrees of freedom (trace of
          the smoother matrix).

    spar: smoothing parameter, typically (but not necessarily) in
          (0,1].  The coefficient lambda of the integral of the squared
          second derivative in the fit (penalized log likelihood)
          criterion is a monotone function of `spar', see the details
          below.

      cv: ordinary (`TRUE') or `generalized' (`FALSE')
          cross-validation.

all.knots: if `TRUE', all points in `x' are uses as knots. If `FALSE',
          a suitably fine grid of knots is used.

df.offset: allows the degrees of freedom to be increased by `df.offset'
          in the GCV criterion.

 penalty: the coefficient of the penalty for degrees of freedom in the
          GCV criterion.

control.spar: optional list with named components controlling the root
          finding when the smoothing parameter `spar' is computed.

          Note that this is partly experimental and may change with
          general spar computation improvements!

          low: lower bound for `spar'; defaults to -1.5 (used to
               implicitly default to 0 in R versions earlier than 1.4).

          high: upper bound for `spar'; defaults to +1.5.

          tol: the absolute precision (tolerance) used; defaults to
               1e-4 (formerly 1e-3).

          eps: the relative precision used; defaults to 2e-8 (formerly
               0.00244).

          trace: logical indicating if iterations should be traced.

          maxit: integer giving the maximal number of iterations;
               defaults to 500.

          Note that `spar' is only searched for in the interval [low,
          high]. 

Details:

     The `x' vector should contain at least ten distinct values.

     The computational lambda used (as a function of `spar') is lambda
     = r * 256^(3*spar - 1) where r = tr(X' W^2 X) / tr(Sigma), Sigma
     is the matrix given by Sigma[i,j] = Integral B''[i](t) B''[j](t)
     dt, X is given by X[i,j] = B[j](x[i]), W^2 is the diagonal matrix
     of scaled weights, `W = diag(w)/n' (i.e., the identity for default
     weights), and B[k](.) is the k-th B-spline.

     Note that with these definitions, f_i = f(x_i), and the B-spline
     basis representation f = X c (i.e. c is the vector of spline
     coefficients), the penalized log likelihood is L = (y - f)' W^2 (y
     - f) + lambda c' Sigma c, and hence c is the solution of the
     (ridge regression) (X' W^2 X + lambda Sigma) c = X' W^2 y.

     If `spar' is missing or `NULL', the value of `df' is used to
     determine the degree of smoothing.  If both are missing,
     leave-one-out cross-validation is used to determine lambda. Note
     that from the above relation, `spar' is spar = s0 + 0.0601 *
     log(lambda), which is intentionally different from the S-plus
     implementation of `smooth.spline' (where `spar' is proportional to
     lambda).  In R's (log lambda) scale, it makes more sense to vary
     `spar' linearly.

     Note however that currently the results may be come very
     unreliable for `spar' values smaller than about -1 or -2.  The
     same may happen for values larger than 2 or so. Don't think of
     setting `spar' or the controls `low' and `high' outside such a
     safe range, unless you know what you are doing!

     The ``generalized'' cross-validation method will work correctly
     when there are duplicated points in `x'.  However, it is ambiguous
     what leave-one-out cross-validation means with duplicated points,
     and the internal code uses an approximation that involves leaving
     out groups of duplicated points.  `cv=TRUE' is best avoided in
     that case.

Value:

     An object of class `"smooth.spline"' with components 

       x: the distinct `x' values in increasing order.

       y: the fitted values corresponding to `x'.

       w: the weights used at the unique values of `x'.

     yin: the y values used at the unique `y' values.

     lev: leverages, the diagonal values of the smoother matrix.

 cv.crit: (generalized) cross-validation score.

pen.crit: penalized criterion

    crit: the criterion value minimized in the underlying `.Fortran'
          routine `sslvrg'.

      df: equivalent degrees of freedom used.  Note that (currently)
          this value may become quite unprecise when the true `df' is
          between and 1 and 2. 

    spar: the value of `spar' computed or given.

  lambda: the value of lambda corresponding to `spar', see the details
          above.

  iparms: named integer(3) vector where `..$ipars["iter"]' gives number
          of spar computing iterations used.

     fit: list for use by `predict.smooth.spline'.

    call: the matched call.

Author(s):

     B.D. Ripley and Martin Maechler (spar/lambda, etc).

See Also:

     `predict.smooth.spline'

Examples:

     data(cars)
     attach(cars)
     plot(speed, dist, main = "data(cars)  &  smoothing splines")
     cars.spl <- smooth.spline(speed, dist)
     (cars.spl)
     ## This example has duplicate points, so avoid cv=TRUE

     lines(cars.spl, col = "blue")
     lines(smooth.spline(speed, dist, df=10), lty=2, col = "red")
     legend(5,120,c(paste("default [C.V.] => df =",round(cars.spl$df,1)),
                    "s( * , df = 10)"), col = c("blue","red"), lty = 1:2,
            bg='bisque')
     detach()

     ##-- artificial example
     y18 <- c(1:3,5,4,7:3,2*(2:5),rep(10,4))
     xx  <- seq(1,length(y18), len=201)
     (s2  <- smooth.spline(y18)) # GCV
     (s02 <- smooth.spline(y18, spar = 0.2))
     plot(y18, main=deparse(s2$call), col.main=2)
     lines(s2, col = "gray"); lines(predict(s2, xx), col = 2)
     lines(predict(s02, xx), col = 3); mtext(deparse(s02$call), col = 3)

     ## The following shows the problematic behavior of `spar' searching:
     (s2  <- smooth.spline(y18,          con=list(trace=TRUE,tol=1e-6, low= -1.5)))
     (s2m <- smooth.spline(y18, cv=TRUE, con=list(trace=TRUE,tol=1e-6, low= -1.5)))
     ## both above do quite similarly (Df = 8.5 +- 0.2)

