smooth.construct.bt.smooth.spec: B-spline tensor product smooths with general penalties

In mgcv: Mixed GAM Computation Vehicle with Automatic Smoothness Estimation

B-spline tensor product smooths with general penalties

Description

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, 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 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

## S3 method for class 'bt.smooth.spec'
smooth.construct(object, data, knots)
## S3 method for class 'b.tensor'
Predict.matrix(object, data)

Arguments

object	a smooth specification object, usually generated by a term s(x,bs="bs",...)
data	a list containing just the data (including any by variable) required by this term, with names corresponding to object$term (and object$by). The by variable is the last element.
knots	a list containing any knots supplied for basis setup — in same order and with same names as data. Can be NULL. See details for further information.

Details

Sets up a tensor product basis from marginal one dimensional B-spline bases. Drops basis functions with no data in span, unless 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 s(x,z,m=M,bs="bt"). The penalty specification is very flexible and is controlled by M.

• If 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 M-1 derivatives.

• If M is a single number x.z then an order x B-spline tensor product basis is required with an order z thin plate spline penalty. z < x.

• If M is a vector it specifies the B-spline order for each margin and the penalty for the ith margin will be derivative orderM[i]-1.

• If M is a two column matrix then M[i,1] is the basis order and M[i,2] the penalty derivative order for the ith margin.

• If M is a list then M[[1]] is a vector of basis orders for each margin and the remaining list elements specify penalties. The jth column of M[[i]] (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 L. lsp = L %*% lsp0 where there are fewer lsp0 log smoothing parameters than lsp. L is supplied as a named element of M.

Note that each derivative penalty is the integral of the given derivative over the span of the retained tensor product basis functions.

Value

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

WARNING

Note the intuitively sensible way that spline order is specified here.

Author(s)

Simon N. Wood [e-mail]. Extrapolation ideas joint with David Miller.

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 https://arxiv.org/abs/1605.02446 \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1007/s11222-016-9666-x")}

See Also

b.spline

Examples

  require(mgcv)
  set.seed(1)
  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 <- 800
  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)

mgcv documentation built on Nov. 3, 2026, 1:08 a.m.