te package:mgcv R Documentation _D_e_f_i_n_e _t_e_n_s_o_r _p_r_o_d_u_c_t _s_m_o_o_t_h_s _i_n _G_A_M _f_o_r_m_u_l_a_e _D_e_s_c_r_i_p_t_i_o_n: Function used in definition of tensor product smooth terms within 'gam' model formulae. The function does not evaluate a smooth - it exists purely to help set up a model using tensor product based smooths. Designed to construct tensor products from any marginal smooths with a basis-penalty representation (with the restriction that each marginal smooth must have only one penalty). _U_s_a_g_e: te(..., k=NA,bs="cr",m=NA,d=NA,by=NA,fx=FALSE, mp=TRUE,np=TRUE,xt=NULL,id=NULL,sp=NULL) _A_r_g_u_m_e_n_t_s: ...: a list of variables that are the covariates that this smooth is a function of. k: the dimension(s) of the bases used to represent the smooth term. If not supplied then set to '5^d'. If supplied as a single number then this basis dimension is used for each basis. If supplied as an array then the elements are the dimensions of the component (marginal) bases of the tensor product. See 'choose.k' for further information. bs: array (or single character string) specifying the type for each marginal basis. '"cr"' for cubic regression spline; '"cs"' for cubic regression spline with shrinkage; '"cc"' for periodic/cyclic cubic regression spline; '"tp"' for thin plate regression spline; '"ts"' for t.p.r.s. with extra shrinkage. See 'smooth.terms' for details and full list. User defined bases can also be used here (see 'smooth.construct' for an example). If only one basis code is given then this is used for all bases. m: The order of the penalty (for smooth classes that use this) for each term. If a single number is given then it is used for all terms. 'NA' autoinitializes. 'm' is ignored by some bases (e.g. '"cr"'). 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 1-dimensional basis, then set 'd=c(2,1)'. 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 'gam.models' for further details. May also be a matrix if covariates are matrices: in this case implements linear functional of a smooth (see 'gam.models' and 'linear.functional.terms' for details). fx: indicates whether the term is a fixed d.f. regression spline ('TRUE') or a penalized regression spline ('FALSE'). mp: 'TRUE' to use multiple penalties for the smooth. 'FALSE' to use only a single penalty: single penalties are not recommended - they tend to allow only rather wiggly models. np: 'TRUE' to use the `normal parameterization' for a tensor product smooth. This represents any 1-d marginal smooths via parameters that are function values at `knots', spread evenly through the data. The parameterization makes the penalties easily interpretable, however it can reduce numerical stability in some cases. 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 'id' then they will have the same smoothing paramsters, and, by default, the same bases (first occurance defines basis type, but data from all terms used in basis construction). 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 auto-initialization. Over-rides values supplied in 'sp' argument to 'gam'. Ignored by 'gamm'. _D_e_t_a_i_l_s: 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. An option for operating with a single penalty (The Kronecker product of the marginal penalties) is provided, but it is rarely of practical use: the penalty is typically so rank deficient that even the smoothest resulting model will have rather high estimated degrees of freedom. 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. Note also that GAMs constructed from lower rank tensor product smooths are nested within GAMs constructed from higher rank tensor product smooths if the same marginal bases are used in both cases (the marginal smooths themselves are just special cases of tensor product smooths.) The `normal parameterization' ('np=TRUE') re-parameterizes 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'. The function does not evaluate the variable arguments. _V_a_l_u_e: 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 'smooth.spec' objects of the type returned by 's', defining the basis from which the tensor product smooth is constructed. 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 'by' variable as text ('"NA"' for none). fx: logical array with element for each penalty of the term (tensor product smooths have multiple penalties). 'TRUE' if the penalty is to be ignored, 'FALSE', otherwise. 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: 'TRUE' is multiple penalties are to be used (default). np: 'TRUE' to re-parameterize 1-D marginal smooths in terms of function values (defualt). id: the 'id' argument supplied to 'te'. sp: the 'sp' argument supplied to 'te'. _A_u_t_h_o_r(_s): Simon N. Wood simon.wood@r-project.org _R_e_f_e_r_e_n_c_e_s: Wood, S.N. (2006a) Low rank scale invariant tensor product smooths for generalized additive mixed models. Biometrics 62(4):1025-1036 _S_e_e _A_l_s_o: 's','gam','gamm' _E_x_a_m_p_l_e_s: # following shows how tensor pruduct deals nicely with # badly scaled covariates (range of x 5% of range of z ) test1<-function(x,z,sx=0.3,sz=0.4) { x<-x*20 (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<-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~te(x,z,bs=c("tp","tp"))) vis.gam(b3);title("tensor product") par(old.par) test2<-function(u,v,w,sv=0.3,sw=0.4) { ((pi**sv*sw)*(1.2*exp(-(v-0.2)^2/sv^2-(w-0.3)^2/sw^2)+ 0.8*exp(-(v-0.7)^2/sv^2-(w-0.8)^2/sw^2)))*(u-0.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 thin plate regression spline and 1D cr spline b <- gam(y~te(v,w,u,k=c(30,5),d=c(2,1),bs=c("tp","cr"))) op <- par(mfrow=c(2,2)) vis.gam(b,cond=list(u=0),color="heat",zlim=c(-0.2,3.5)) vis.gam(b,cond=list(u=.33),color="heat",zlim=c(-0.2,3.5)) vis.gam(b,cond=list(u=.67),color="heat",zlim=c(-0.2,3.5)) vis.gam(b,cond=list(u=1),color="heat",zlim=c(-0.2,3.5)) par(op)