bs                  package:splines                  R Documentation

B-Spline Basis for Polynomial Splines

Description:

     Generate the B-spline basis matrix for a polynomial spline.

Usage:

     bs(x, df = NULL, knots = NULL, degree = 3, intercept = FALSE,
        Boundary.knots = range(x))

Arguments:

       x: the predictor variable.  Missing values are allowed.

      df: degrees of freedom; one can specify 'df' rather than 'knots';
          'bs()' then chooses 'df-degree-1' knots at suitable quantiles
          of 'x' (which will ignore missing values).

   knots: the _internal_ breakpoints that define the spline.  The
          default is 'NULL', which results in a basis for ordinary
          polynomial regression.  Typical values are the mean or median
          for one knot, quantiles for more knots.  See also
          'Boundary.knots'.

  degree: degree of the piecewise polynomial-default is 3 for cubic
          splines.

intercept: if 'TRUE', an intercept is included in the basis; default is
          'FALSE'.

Boundary.knots: boundary points at which to anchor the B-spline basis
          (default the range of the data). If both 'knots' and
          'Boundary.knots' are supplied, the basis parameters do not
          depend on 'x'. Data can extend beyond 'Boundary.knots'.

Value:

     A matrix of dimension 'length(x) * df', where either 'df' was
     supplied or if 'knots' were supplied, 'df = length(knots) + 3 +
     intercept'.  Attributes are returned that  correspond to the
     arguments to 'bs', and explicitly give the 'knots',
     'Boundary.knots' etc for use by 'predict.bs()'.

     'bs()' is based on the function 'spline.des()'. It generates a
     basis matrix for representing the family of piecewise polynomials
     with the specified interior knots and degree, evaluated at the
     values of 'x'.  A primary use is in modeling formulas to directly
     specify a piecewise polynomial term in a model.

References:

     Hastie, T. J. (1992) Generalized additive models. Chapter 7 of
     _Statistical Models in S_ eds J. M. Chambers and T. J. Hastie,
     Wadsworth & Brooks/Cole.

See Also:

     'ns', 'poly', 'smooth.spline', 'predict.bs', 'SafePrediction'

Examples:

     require(stats); require(graphics)
     bs(women$height, df = 5)
     summary(fm1 <- lm(weight ~ bs(height, df = 5), data = women))

     ## example of safe prediction
     plot(women, xlab = "Height (in)", ylab = "Weight (lb)")
     ht <- seq(57, 73, len = 200)
     lines(ht, predict(fm1, data.frame(height=ht)))

     ## Consistency:
     x <- c(1:3,5:6)
     stopifnot(identical(bs(x), bs(x, df = 3)),
               !is.null(kk <- attr(bs(x), "knots")),# not true till 1.5.1
               length(kk) == 0)

