\HeaderA{smooth.construct.ps.smooth.spec}{P-splines in GAMs}{smooth.construct.ps.smooth.spec}
\aliasA{cyclic.p.spline}{smooth.construct.ps.smooth.spec}{cyclic.p.spline}
\aliasA{p.spline}{smooth.construct.ps.smooth.spec}{p.spline}
\aliasA{smooth.construct.cp.smooth.spec}{smooth.construct.ps.smooth.spec}{smooth.construct.cp.smooth.spec}
\keyword{models}{smooth.construct.ps.smooth.spec}
\keyword{regression}{smooth.construct.ps.smooth.spec}
\begin{Description}\relax
\code{\LinkA{gam}{gam}} can use univariate P-splines as proposed by Eilers and Marx (1996), 
specified via terms like \code{s(x,bs="ps")}. These terms use B-spline bases 
penalized by discrete penalties applied directly to 
the basis coefficients. Cyclic P-splines are specified by model terms like \code{s(x,bs="cp",...)}. 
These bases can be used in tensor product smooths (see \code{\LinkA{te}{te}}).

The advantage of P-splines is the flexible way that penalty and basis order can be mixed. This often provides a useful way of `taming' an otherwise poorly behave smooth. However, in regular use, splines with derivative based penalties (e.g. \code{"tp"} or \code{"cr"} bases) tend to result in slightly better MSE performance, presumably because the good approximation theoretic properties of splines are rather closely connected to the use of derivative penalties.
\end{Description}
\begin{Usage}
\begin{verbatim}
## S3 method for class 'ps.smooth.spec':
smooth.construct(object, data, knots)
## S3 method for class 'cp.smooth.spec':
smooth.construct(object, data, knots)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{object}] a smooth specification object, usually generated by a term \code{s(x,bs="ps",...)} or 
\code{s(x,bs="cp",...)}
\item[\code{data}] a list containing just the data (including any \code{by} variable) required by this term, 
with names corresponding to \code{object\$term} (and \code{object\$by}). The \code{by} variable 
is the last element.
\item[\code{knots}] a list containing any knots supplied for basis setup --- in same order and with same names as \code{data}. 
Can be \code{NULL}
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
A  smooth term of the form \code{s(x,bs="ps",m=c(2,3))} specifies a 2nd order P-spline basis (cubic spline), 
with a third order difference penalty (0th order is a ridge penalty) on the coefficients. If \code{m} is a single number then it is taken as the basis order and penalty order. The default is the `cubic spline like' \code{m=c(2,2)}.

The default basis dimension, \code{k}, is the larger of 10 and \code{m[1]+1} for a \code{"ps"} terms and the larger of 10 and \code{m[1]} for a \code{"cp"} term. \code{m[1]+1} and \code{m[1]} are the lower limits on basis dimension for the two types. 

If knots are supplied, then the number of knots should be one more than the basis dimension (i.e. \code{k+1}) for a \code{"cp"}smooth. For the \code{"ps"} basis the number of supplied knots should be \code{k + m[1] + 2}, and the range of the middle 
\code{k-m[1]} knots should include all the covariate values. See example.
P-splines don't make much sense with uneven knot spacing.
\end{Details}
\begin{Value}
An object of class \code{"ps.smooth"} or \code{"cp.smooth"}. See \code{\LinkA{smooth.construct}{smooth.construct}}, 
for the elements that this object will contain.
\end{Value}
\begin{Author}\relax
Simon N. Wood \email{simon.wood@r-project.org}
\end{Author}
\begin{References}\relax
Eilers, P.H.C. and B.D. Marx (1996) Flexible Smoothing with B-splines and Penalties. 
Statistical Science, 11(2):89-121
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{cSplineDes}{cSplineDes}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## see ?gam
## cyclic example ...
  set.seed(6)
  x <- sort(runif(200)*10)
  z <- runif(200)
  f <- sin(x*2*pi/10)+.5
  y <- rpois(exp(f),exp(f)) 

## finished simulating data, now fit model...
  b <- gam(y ~ s(x,bs="cp") + s(z,bs="ps"),family=poisson)

## example with supplied knots...
  bk <- gam(y ~ s(x,bs="cp",k=12) + s(z,bs="ps",k=13),family=poisson,
                      knots=list(x=seq(0,10,length=13),z=(-3):13))

## plot results...
  par(mfrow=c(2,2))
  plot(b,select=1,shade=TRUE);lines(x,f-mean(f),col=2)
  plot(b,select=2,shade=TRUE);lines(z,0*z,col=2)
  plot(bk,select=1,shade=TRUE);lines(x,f-mean(f),col=2)
  plot(bk,select=2,shade=TRUE);lines(z,0*z,col=2)
  
\end{ExampleCode}
\end{Examples}

