\Header{ns}{Generate a Basis Matrix for Natural Cubic Splines}
\begin{Usage}
\begin{verbatim}
ns(x, df, knots, intercept=F, Boundary.knots)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\texttt{x}] the predictor variable.
\item[\texttt{df}] degrees of freedom. One can supply \texttt{df} rather than
knots; \texttt{ns()} then chooses \texttt{df-1-intercept} knots at
suitably chosen quantiles of \texttt{x}.
\item[\texttt{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 \texttt{x}.  Typical values are the
mean or median for one knot, quantiles for more knots. See also
\texttt{Boundary.knots}.
\item[\texttt{intercept}] if \texttt{TRUE}, an intercept is included in the
basis; default is \texttt{FALSE}.
\item[\texttt{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 \texttt{knots} and \texttt{Boundary.knots} are
supplied, the basis parameters do not depend on \texttt{x}. Data can
extend beyond \texttt{Boundary.knots}
\end{ldescription}
\end{Arguments}
\begin{Value}
a matrix of dimension \texttt{length(x) * df} where either \texttt{df} was
supplied or if \texttt{knots} were supplied,
\texttt{df = length(knots) + 1 + intercept}.
Attributes are returned that correspond to the arguments to \texttt{ns},
and explicitly give the \texttt{knots}, \texttt{Boundary.knots} etc for
use by \texttt{predict.ns()}.

\texttt{ns()} is based on the function \texttt{spline.des()} written by
Douglas Bates.  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, else default to the extremes of the
data.  A primary use is in modeling formula to directly specify a
natural spline term in a model.

Beware of making predictions with new \texttt{x} values when \texttt{df}
is used as an argument. Either use \texttt{safe.predict.gam()}, or else
specify \texttt{knots} and \texttt{Boundary.knots}.\end{Value}
\begin{SeeAlso}
\texttt{bs}, \texttt{poly}, \texttt{lo}, \texttt{s}, \texttt{predict.ns}\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
lsfit(ns(x,5),y)
lm(y ~ ns(age, 4) + ns(income, 4)) # an additive model 
fit <- lm(y ~ ns(age, knots=c(20,30), B=c(10,60)))
predict(fit, new.age) #safe predictions because explicit knot sequence was supplied.
\end{ExampleCode}
\end{Examples}

