te                   package:mgcv                   R Documentation

Define tensor product smooths in GAM formulae

Description:

     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).

Usage:

     te(..., k=NA,bs="cr",m=NA,d=NA,by=NA,fx=FALSE,
                   mp=TRUE,np=TRUE,xt=NULL,id=NULL,sp=NULL)

Arguments:

     ...: 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'.

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.

     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.

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 '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'.

Author(s):

     Simon N. Wood simon.wood@r-project.org

References:

     Wood, S.N. (2006a) Low rank scale invariant tensor product smooths
     for generalized additive mixed models. Biometrics 62(4):1025-1036

     <URL: http://www.maths.bath.ac.uk/~sw283/>

See Also:

     's','gam','gamm'

Examples:

     # 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 a 2-d thin plate regression spline and 1-d 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)

