te {mgcv}  R Documentation 
Define tensor product smooths or tensor product interactions in GAM formulae
Description
Functions used for the definition of tensor product smooths and interactions within
gam
model formulae. te
produces a full tensor product smooth, while ti
produces a tensor product interaction, appropriate when the main effects (and any lower
interactions) are also present.
The functions do not evaluate the smooth  they exists purely to help set up a model using tensor product based smooths. Designed to construct tensor products from any marginal smooths with a basispenalty representation (with the restriction that each marginal smooth must have only one penalty).
Usage
te(..., k=NA,bs="cr",m=NA,d=NA,by=NA,fx=FALSE,
np=TRUE,xt=NULL,id=NULL,sp=NULL,pc=NULL)
ti(..., k=NA,bs="cr",m=NA,d=NA,by=NA,fx=FALSE,
np=TRUE,xt=NULL,id=NULL,sp=NULL,mc=NULL,pc=NULL)
Arguments
... 
a list of variables that are the covariates that this
smooth is a function of. Transformations whose form depends on
the values of the data are best avoided here: e.g. 
k 
the dimension(s) of the bases used to represent the smooth term.
If not supplied then set to 
bs 
array (or single character string) specifying the type for each
marginal basis. 
m 
The order of the spline and its penalty (for smooth classes that use this) for each term.
If a single number is given then it is used for all terms. A vector can be used to
supply a different 
d 
array of marginal basis dimensions. For example if you want a smooth for 3 covariates
made up of a tensor product of a 2 dimensional t.p.r.s. basis and a 1dimensional basis, then
set 
by 
a numeric or factor variable of the same dimension as each covariate.
In the numeric vector case the elements multiply the smooth evaluated at the corresponding
covariate values (a ‘varying coefficient model’ results).
In the factor case causes a replicate of the smooth to be produced for
each factor level. See 
fx 
indicates whether the term is a fixed d.f. regression
spline ( 
np 

xt 
Either a single object, providing any extra information to be passed to each marginal basis constructor, or a list of such objects, one for each marginal basis. 
id 
A label or integer identifying this term in order to link its smoothing
parameters to others of the same type. If two or more smooth terms have the same

sp 
any supplied smoothing parameters for this term. Must be an array of the same
length as the number of penalties for this smooth. Positive or zero elements are taken as fixed
smoothing parameters. Negative elements signal autoinitialization. Overrides values supplied in

mc 
For 
pc 
If not 
Details
Smooths of several covariates can be constructed from tensor products of the bases
used to represent smooths of one (or sometimes more) of the covariates. To do this ‘marginal’ bases
are produced with associated model matrices and penalty matrices, and these are then combined in the
manner described in tensor.prod.model.matrix
and tensor.prod.penalties
, to produce
a single model matrix for the smooth, but multiple penalties (one for each marginal basis). The basis dimension
of the whole smooth is the product of the basis dimensions of the marginal smooths.
Tensor product smooths are especially useful for representing functions of covariates measured in different units, although they are typically not quite as nicely behaved as t.p.r.s. smooths for well scaled covariates.
It is sometimes useful to investigate smooth models with a maineffects + interactions structure, for example
f_1(x) + f_2(z) + f_3(x,z)
This functional ANOVA decomposition is supported by ti
terms, which produce tensor product interactions from which the main effects have been excluded, under the assumption that they will be included separately. For example the ~ ti(x) + ti(z) + ti(x,z)
would produce the above main effects + interaction structure. This is much better than attempting the same thing with s
or te
terms representing the interactions (although mgcv does not forbid it). Technically ti
terms are very simple: they simply construct tensor product bases from marginal smooths to which identifiability constraints (usually sumtozero) have already been applied: correct nesting is then automatic (as with all interactions in a GLM framework). See Wood (2017, section 5.6.3).
The ‘normal parameterization’ (np=TRUE
) reparameterizes the marginal
smooths of a tensor product smooth so that the parameters are function values
at a set of points spread evenly through the range of values of the covariate
of the smooth. This means that the penalty of the tensor product associated
with any particular covariate direction can be interpreted as the penalty of
the appropriate marginal smooth applied in that direction and averaged over
the smooth. Currently this is only done for marginals of a single
variable. This parameterization can reduce numerical stability when used
with marginal smooths other than "cc"
, "cr"
and "cs"
: if
this causes problems, set np=FALSE
.
Note that tensor product smooths should not be centred (have identifiability constraints imposed) if any marginals would not need centering. The constructor for tensor product smooths ensures that this happens.
The function does not evaluate the variable arguments.
Value
A class tensor.smooth.spec
object defining a tensor product smooth
to be turned into a basis and penalties by the smooth.construct.tensor.smooth.spec
function.
The returned object contains the following items:
margin 
A list of 
term 
An array of text strings giving the names of the covariates that the term is a function of. 
by 
is the name of any 
fx 
logical array with element for each penalty of the term
(tensor product smooths have multiple penalties). 
label 
A suitable text label for this smooth term. 
dim 
The dimension of the smoother  i.e. the number of covariates that it is a function of. 
mp 

np 

id 
the 
sp 
the 
inter 

mc 
the argument 
Author(s)
Simon N. Wood simon.wood@rproject.org
References
Wood, S.N. (2006) Low rank scale invariant tensor product smooths for generalized additive mixed models. Biometrics 62(4):10251036 doi:10.1111/j.15410420.2006.00574.x
Wood S.N. (2017) Generalized Additive Models: An Introduction with R (2nd edition). Chapman and Hall/CRC Press. doi:10.1201/9781315370279
https://www.maths.ed.ac.uk/~swood34/
See Also
s
,gam
,gamm
,
smooth.construct.tensor.smooth.spec
Examples
# following shows how tensor pruduct deals nicely with
# badly scaled covariates (range of x 5% of range of z )
require(mgcv)
test1 < function(x,z,sx=0.3,sz=0.4) {
x < x*20
(pi**sx*sz)*(1.2*exp((x0.2)^2/sx^2(z0.3)^2/sz^2)+
0.8*exp((x0.7)^2/sx^2(z0.8)^2/sz^2))
}
n < 500
old.par < par(mfrow=c(2,2))
x < runif(n)/20;z < runif(n);
xs < seq(0,1,length=30)/20;zs < seq(0,1,length=30)
pr < data.frame(x=rep(xs,30),z=rep(zs,rep(30,30)))
truth < matrix(test1(pr$x,pr$z),30,30)
f < test1(x,z)
y < f + rnorm(n)*0.2
b1 < gam(y~s(x,z))
persp(xs,zs,truth);title("truth")
vis.gam(b1);title("t.p.r.s")
b2 < gam(y~te(x,z))
vis.gam(b2);title("tensor product")
b3 < gam(y~ ti(x) + ti(z) + ti(x,z))
vis.gam(b3);title("tensor anova")
## now illustrate partial ANOVA decomp...
vis.gam(b3);title("full anova")
b4 < gam(y~ ti(x) + ti(x,z,mc=c(0,1))) ## note z constrained!
vis.gam(b4);title("partial anova")
plot(b4)
par(old.par)
## now with a multivariate marginal....
test2<function(u,v,w,sv=0.3,sw=0.4)
{ ((pi**sv*sw)*(1.2*exp((v0.2)^2/sv^2(w0.3)^2/sw^2)+
0.8*exp((v0.7)^2/sv^2(w0.8)^2/sw^2)))*(u0.5)^2*20
}
n < 500
v < runif(n);w<runif(n);u<runif(n)
f < test2(u,v,w)
y < f + rnorm(n)*0.2
# tensor product of 2D Duchon spline and 1D cr spline
m < list(c(1,.5),rep(0,0)) ## example of list form of m
b < gam(y~te(v,w,u,k=c(30,5),d=c(2,1),bs=c("ds","cr"),m=m))
plot(b)