| % File src/library/splines/man/ns.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2018 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{ns} |
| \alias{ns} |
| \title{Generate a Basis Matrix for Natural Cubic Splines} |
| \description{ |
| Generate the B-spline basis matrix for a natural cubic spline. |
| } |
| \usage{ |
| ns(x, df = NULL, knots = NULL, intercept = FALSE, |
| Boundary.knots = range(x)) |
| } |
| \arguments{ |
| \item{x}{the predictor variable. Missing values are allowed.} |
| \item{df}{degrees of freedom. One can supply \code{df} rather than |
| knots; \code{ns()} then chooses \code{df - 1 - intercept} knots at |
| suitably chosen quantiles of \code{x} (which will ignore missing |
| values). The default, \code{df = NULL}, sets the number of |
| inner knots as \code{length(knots)}.} |
| \item{knots}{breakpoints that define the spline. The default is no |
| knots; together with the natural boundary conditions this results in |
| a basis for linear regression on \code{x}. Typical values are the |
| mean or median for one knot, quantiles for more knots. See also |
| \code{Boundary.knots}.} |
| \item{intercept}{if \code{TRUE}, an intercept is included in the |
| basis; default is \code{FALSE}.} |
| \item{Boundary.knots}{boundary points at which to impose the natural |
| boundary conditions and anchor the B-spline basis (default the range |
| of the data). If both \code{knots} and \code{Boundary.knots} are |
| supplied, the basis parameters do not depend on \code{x}. Data can |
| extend beyond \code{Boundary.knots}} |
| } |
| \details{ |
| \code{ns} is based on the function \code{\link{splineDesign}}. It |
| generates a basis matrix for representing the family of |
| piecewise-cubic splines with the specified sequence of |
| interior knots, and the natural boundary conditions. These enforce |
| the constraint that the function is linear beyond the boundary knots, |
| which can either be supplied or default to the extremes of the |
| data. |
| |
| A primary use is in modeling formula to directly specify a |
| natural spline term in a model: see the examples. |
| } |
| |
| \value{ |
| A matrix of dimension \code{length(x) * df} where either \code{df} was |
| supplied or if \code{knots} were supplied, |
| \code{df = length(knots) + 1 + intercept}. |
| Attributes are returned that correspond to the arguments to \code{ns}, |
| and explicitly give the \code{knots}, \code{Boundary.knots} etc for |
| use by \code{predict.ns()}. |
| } |
| \seealso{ |
| \code{\link{bs}}, \code{\link{predict.ns}}, \code{\link{SafePrediction}} |
| } |
| \references{ |
| Hastie, T. J. (1992) |
| Generalized additive models. |
| Chapter 7 of \emph{Statistical Models in S} |
| eds J. M. Chambers and T. J. Hastie, Wadsworth & Brooks/Cole. |
| } |
| \examples{ |
| require(stats); require(graphics) |
| ns(women$height, df = 5) |
| summary(fm1 <- lm(weight ~ ns(height, df = 5), data = women)) |
| |
| ## To see what knots were selected |
| attr(terms(fm1), "predvars") |
| |
| ## example of safe prediction |
| plot(women, xlab = "Height (in)", ylab = "Weight (lb)") |
| ht <- seq(57, 73, length.out = 200) ; nD <- data.frame(height = ht) |
| lines(ht, p1 <- predict(fm1, nD)) |
| stopifnot(all.equal(p1, predict(update(fm1, . ~ |
| splines::ns(height, df=5)), nD))) |
| # not true in R < 3.5.0 |
| \dontshow{ |
| ## Consistency: |
| x <- c(1:3, 5:6) |
| stopifnot(identical(ns(x), ns(x, df = 1)), |
| identical(ns(x, df = 2), |
| ns(x, df = 2, knots = NULL)), # not true till 2.15.2 |
| !is.null(kk <- attr(ns(x), "knots")), # not true till 1.5.1 |
| length(kk) == 0) |
| } |
| } |
| \keyword{smooth} |