pdTens                 package:mgcv                 R Documentation

Functions implementing a pdMat class for tensor product smooths

Description:

     This set of functions implements an 'nlme' library 'pdMat' class
     to allow tensor product smooths to be estimated by 'lme' as called
     by 'gamm'. Tensor product smooths have a penalty matrix made up of
     a weighted sum of penalty matrices, where the weights are the
     smoothing  parameters. In the mixed model formulation the penalty
     matrix is the inverse of the covariance matrix for  the random
     effects of a term, and the smoothing parameters (times a half) are
     variance parameters to be estimated.  It's not  possible to
     transform the problem to make the required random effects
     covariance matrix look like one of the standard  'pdMat' classes:
     hence the need for the 'pdTens' class. A 'notLog2'
     parameterization ensures that  the parameters are positive. 

     These functions ('pdTens', 'pdConstruct.pdTens',
     'pdFactor.pdTens', 'pdMatrix.pdTens', 'coef.pdTens' and
     'summary.pdTens') would not normally be called directly.

Usage:

     pdTens(value = numeric(0), form = NULL, 
            nam = NULL, data = sys.frame(sys.parent()))

Arguments:

   value: Initialization values for parameters. Not normally used.

    form: A one sided formula specifying the random effects structure.
          The formula should have an attribute 'S' which is a list of
          the penalty matrices the weighted sum of which gives the
          inverse of the  covariance matrix for these random effects.

     nam: a names argument, not normally used with this class.

    data: data frame in which to evaluate formula.

Details:

     If using this class directly note that it is worthwhile scaling
     the 'S' matrices to be of `moderate size', for example by dividing
     each matrix by its largest singular value: this avoids problems
     with 'lme' defaults ('smooth.construct.tensor.smooth.spec' does
     this automatically).  

     This appears to be the minimum set of functions required to
     implement a new 'pdMat' class. 

     Note that while the 'pdFactor' and 'pdMatrix' functions return the
     inverse of the scaled random  effect covariance matrix or its
     factor, the 'pdConstruct' function is sometimes initialised with
     estimates of the scaled covariance matrix, and sometimes
     intialized with its inverse.

Value:

     A class 'pdTens' object, or its coefficients or the matrix it
     represents or the factor of  that matrix. 'pdFactor' returns the
     factor as a vector (packed column-wise) ('pdMatrix' always returns
     a matrix).

Author(s):

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

References:

     Pinheiro J.C. and Bates, D.M. (2000) Mixed effects Models in S and
     S-PLUS. Springer

     The 'nlme' source code.

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

See Also:

     'te'  'gamm'

Examples:

     # see gamm

