smooth.construct.tismd.smooth.spec {scam}

Tensor product interaction with decreasing constraint along the first covariate and unconstrained along the second covariate

Description

This is a special method function for creating tensor product bivariate interaction smooths with decreasing constraint in the first covariate, appropriate when the main effects (and any lower interactions) are also present. It is built by the mgcv constructor function for smooth terms, smooth.construct, and constructed from a pair of single penalty marginal smooths. This tensor product is specified by model terms such as s(x1,x2,k=c(q1,q2),bs="tismd"). See example below.

Usage

## S3 method for class 'tismd.smooth.spec'
smooth.construct(object, data, knots)

Arguments

object

A smooth specification object, generated by an s term in a GAM formula.

data

A data frame or list containing the values of the elements of object$term, with names given by object$term.

knots

An optional list containing the knots corresponding to object$term. If it is NULL then the knot locations are generated automatically.

Details

In some cases, it is helpful to consider models with a main-effects + interactions structure, for example,

f_1(x) + f_2(z) + f_3(x,z)

where f_1 and f_2 are smooth ‘main effects’ and f_3 is a smooth ‘interaction’ subject to decreasing constraint wrt x (f_1 can be subject to decreasing constraint).

Constructing such functional ANOVA decomposition recognises the fact that the tensor produc basis construction is exactly the same as the construction used for any interaction in a linear model. tismd produce tensor product interactions with decreasing constraint along the first covariate from which the main effects have been excluded, under the assumption that they will be included separately. For example, the ~ s(x) + s(z) + s(x,z,bs="tismd") would produce the above main effects + interaction structure. Specifically, the marginal smooths of a tensor product, tismd, are subject to identifiability constraints before constructing the tensor product basis. This results in the interaction smooths that do not include the corresponding main effects. tismd apply SCOP identifiability constraints to the first marginal and sum-to-zero constraints to the second unconstrained marginal. See Wood (2017, section 5.6.3) for ANOVA decompositions of unconstrained smooths.

Value

An object of class "tismd.smooth". In addition to the usual elements of a smooth class documented under smooth.construct of the mgcv library, this object contains:

p.ident

A vector of 0's and 1's for model parameter identification: 1's indicate parameters which will be exponentiated, 0's - otherwise.

Zc

A matrix of identifiability constraints.

margin.bs

A two letter character string indicating the (penalized) smoothing basis to use for the second unconstrained marginal smooth. (eg "cc" for cyclic cubic regression spline).

Author(s)

Natalya Pya [e-mail]

References

Pya, N. and Wood, S.N. (2015) Shape constrained additive models. Statistics and Computing, 25(3), 543-559

Wood S.N. (2017) Generalized Additive Models: An Introduction with R (2nd edition). Chapman and Hall/CRC Press.

See Also

smooth.construct.tesmd1.smooth.spec

smooth.construct.tismi.smooth.spec

Examples

  ## Not run: 
## tensor product `tismd' example... 
  ## simulating data...
require(scam)
test <- function(x,z){
  -exp(4*x)/(1+exp(4*x))-2*sin(pi*z)-(x+1)^0.6*z
}
set.seed(7)
n <- 600
x <- runif(n)*4-1
z <- runif(n)
xs <- seq(-1,3,length=30); zs <- seq(0,1,length=30)
pr <- data.frame(x=rep(xs,30),z=rep(zs,rep(30,30)))
truth <- matrix(test(pr$x,pr$z),30,30)
f <- test(x,z)
y <- f + rnorm(n)*0.3
bi <- scam(y~ ti(x)+ti(z)+ s(x,z,bs="tismd"))
summary(bi)
old.par <- par(mfrow=c(2,2))
persp(xs,zs,truth);title("truth")
vis.scam(bi);title("tismd")

## fitting with "tesmd1" instead...
bc <- scam(y~s(x,z,bs="tesmd1"))
vis.scam(bc);title("tesmd1")
par(old.par)

plot(bi,pages=1,scheme=2)
plot(bi,select=3,scheme=1,zlim=c(-3,3))
 
## End(Not run)