The R Project SVN R-packages

\name{smooth.construct.bt.smooth.spec}
\alias{smooth.construct.bt.smooth.spec}
\alias{Predict.matrix.b.tensor}
\alias{b.spline tensor}
%- Also NEED an `\alias' for EACH other topic documented here.
\title{B-spline tensor product smooths with general penalties}

\description{\code{\link{gam}} can use smoothing splines based on tensor products of univariate B-spline bases
with derivative based penalties. There is considerable flexibility in how the one or more penalties are set up. For example,  
\code{s(x,z,v,bs="bt",m=3)} specifies a 3-way tensor product of cubic splines with three second derivate based penalties: one for each dimension. Another example is \code{s(x,z,bs="bt",m=3.2)}, a 2-way tensor product of cubic splines with a single second derivative based thin plate spline penalty. The tensor products and penalty are only evaluated over the basis functions with support actually including data. See Details.
}

\usage{
\method{smooth.construct}{bt.smooth.spec}(object, data, knots)
\method{Predict.matrix}{b.tensor}(object, data)
}

\arguments{ 
\item{object}{a smooth specification object, usually generated by a term \code{s(x,bs="bs",...)}}

\item{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{knots}{a list containing any knots supplied for basis setup --- in same order and with same names as \code{data}. 
             Can be \code{NULL}. See details for further information.}

}

\value{ An object of class \code{"b.tensor"}. See \code{\link{smooth.construct}}, 
for the elements that this object will contain. Also contains factor(s) of penalty matrix/matrices in \code{D} (\code{crossprod(D[[i]])} gives \code{S[[i]]}), and orthogonal basis for null space of the overall penalty, \code{N}. 
}

\details{Sets up a tensor product basis from marginal one dimensional B-spline bases. Drops basis functions with no data in span, unless \code{knots} is supplied. If it is then knots can either define a bounding box over which penalty is computed, or supply a set of points characterizing the region over which predictions might be required (so not actually knots): the penalty and basis will then be evaluated over the region defined by the data plus points in this `knots' set.

 Consider a typical smooth \code{s(x,z,m=M,bs="bt")}. The penalty specification is very flexible and is controlled by \code{M}.
\itemize{
\item If \code{M} is a single integer it is the B-spline order to use for all margins and there will be one penalty for each
covariate direction, with order \code{M-1} derivatives.
\item If \code{M} is a single number \code{x.z} then an order \code{x} B-spline tensor product basis is required with an order
\code{z} thin plate spline penalty. \code{z} < \code{x}.
\item If \code{M} is a vector it specifies the B-spline order for each margin and the penalty for the ith margin will be derivative order\code{M[i]-1}.
\item If \code{M} is a two column matrix then \code{M[i,1]} is the basis order
and \code{M[i,2]} the penalty derivative order for the ith margin.
\item If \code{M} is a list then \code{M[[1]]} is a vector of basis orders
for each margin and the remaining list elements specify
penalties. The jth column of \code{M[[i]]} (\code{i>1}) gives the order of derivatives for the jth component of this penalty.
If the column has one more element than there are margins then the final element specifies a constant by which to multiply
the penalty. Smoothing parameters can be linked on the log scale via
a matrix \code{L}. \code{lsp = L \%*\% lsp0} where there are fewer
\code{lsp0} log smoothing parameters than \code{lsp}. \code{L} is supplied as
a named element of \code{M}.
}
Note that each derivative penalty is the integral of the given derivative over the span of the retained tensor product basis functions. 
}

\section{WARNING}{Note the intuitively sensible way that spline order is specified here. }

\author{ Simon N. Wood \email{simon.wood@r-project.org}. Extrapolation ideas joint with David Miller.}

\seealso{\code{\link{b.spline}}}

\references{
Wood, S.N. (2017) P-splines with derivative based penalties and tensor product smoothing of unevenly distributed data. Statistics and Computing. 27(4) 985-989 \url{https://arxiv.org/abs/1605.02446} \doi{10.1007/s11222-016-9666-x}
}


\examples{
  require(mgcv)
  set.seed(5)
  ff <- function(x, z, sx = 0.3, sz = 0.4) {
            (pi^sx * sz) * (1.2 * exp(-(x - 0.2)^2/sx^2 - (z - 
                0.3)^2/sz^2) + 0.8 * exp(-(x - 0.7)^2/sx^2 - 
                (z - 0.8)^2/sz^2))
  }

  n <- 2000
  x <- runif(n)
  z <- runif(n)
  f <- ff(x,z)
  v <- (x-.4)^2+z*.2
  y <- f + rnorm(n)*.2
  plot(v,x)

  par(mfrow=c(2,2)); method <- "REML"
  ## list specifying tensor product of cubic B-splines
  ## and 2nd order TPS penalty
  M = list(rep(3,2),matrix(c(2,0,1,0,2,1,1,1,2),3,3))
  b <- gam(y~s(x,v,bs="bt",m=M,k=15),method=method) ## TPS penalty
  plot(b,scheme=2)

  ## Actually the same is built in...
  b <- gam(y~s(x,v,bs="bt",m=3.2,k=15),method=method) ## TPS penalty
  plot(b,scheme=2)

  length(coef(b)) ## note: < 15^2 = 225

  ## product of 4th and cubic spline with 3rd and 2nd order penalties
  b <- gam(y~s(x,v,bs="bt",m=c(4,3),k=15),method=method) 
  plot(b,scheme=2)
  b$sp
  
  ## product of cubic splines with first order penalties
  b <- gam(y~s(x,v,bs="bt",m=cbind(c(3,3),c(1,1)),k=15),method=method) 
  plot(b,scheme=2)


}
\keyword{models} \keyword{regression}%-- one or more ..