s() is used for univariate smooths (section 5.3, p. 201), isotropic smooths of
several variables (section 5.5, 214) and random effects (section 3.5.2, 154).
te() is used to specify tensor product smooths constructed from any singly
penalized marginal smooths usable with s(), according to section 5.6 (p.
227). Examples are provided in sections 7.2.3, 7.4 and 7.7.1, for example.
ti() is used to specify tensor product interactions with the marginal smooths
(and their lower order interactions) excluded, facilitating smooth ANOVA
models as discussed in section 5.6.3 (p. 232), and exemplified in section
7.3.
t2() is used to specify the alternative tensor product smooth construction
discussed in section 5.6.5 (p. 235), which is especially useful for
generalized additive mixed modelling with the gamm4 package described in
section 7.7.
The first arguments to all these functions are the covariates of the smooth.
Some further arguments control the details of the smoother. The most important
are
bs is a short character string specifying the type of basis. e.g. "cr" for cubic
regression spline, "ds" for Duchon spline, etc. It may be a vector in the
tensor product case, if different types of basis are required for different
marginals.
k is the basis dimension, or marginal basis dimension (tensor case). It can also
be a vector in the tensor case, specifying a dimension for each marginal.
m specifies the order of basis and penalty, in a basis specific manner.
id labels the smooth. Smooths sharing a label all have the same smoothing
parameter (assuming that they are of the same smoother type).
by is the name of a variable by which the smooth should be multiplied (metric
case), or each level of which should have a separate copy of the smooth
(factor case).
by variables are the means for implementing ‘varying coefficient models’,
such as that used in section 7.5.3. Suppose, for example, that we have metric
variables x and z and want to specify a linear predictor term ‘f(xi)zi’ where f is
a smooth function. The model formula entry for this would be s(x,by=z).
Only one by variable is allowed per smooth, but any smooth with multiple
covariates (specified by s, te, ti or t2) can also have a by variable. Note
that, provided the by variable takes more than one value, such terms are
identifiable without a sum-to-zero constraint, and so they are left
unconstrained.
Metric by variables combined with a summation convention are the means
by which linear functionals of smooths can be incorporated into the linear
predictor. Examples are provided in sections 7.4.2 and 7.11.1. The idea is that
if the covariates of the smooth and the by variable are all matrices, then a
summation across rows is implied. For example if X, Z and L are all matrices
then s(X, Z,by=L) specifies the term Σk f(Xik, Zik)Lik in the linear predictor.
Tensor terms also support the convention.
by variables also facilitate ‘smooth-factor’ interactions, in which we have a
separate smooth of one or more covariates for each level of a factor by
variable. For example, suppose we have metric variables x and z and factor
variable g with three levels. Let g(i) denote the level of g corresponding to
observation i. Then te(z,x,by=g) would contribute the terms ‘fg(i) (xi, zi)’ to
the model linear predictor. That is, which of three separate smooth functions of
x and z contributes to the linear predictor depends on which of the three levels
of g applies for observation i. Again s, te, ti or t2 terms all work in the
same way regardless of the number of their covariates. To avoid confounding
problems the smooths are all subject to sum to zero constraints, which usually
means that the main effect of g should also be included in the model
specification. For example, g + te(z, x,by=g). Factor by variables can not
be mixed with the summation convention.† When there are several factor by
variables then identifiability can get tricky, and it can then be useful to employ
ordered factor by variables. If a factor by is an ordered factor then no smooth
is generated for its first level.
References
Wood, S. N. (2017). Generalized Additive Models: An Introduction with R (2nd ed.). CRC Press.