extract.lme.cov             package:mgcv             R Documentation

Extract the data covariance matrix from an lme object

Description:

     This is a service routine for 'gamm'. Extracts  the estimated
     covariance matrix of the data from an 'lme' object, allowing the 
     user control about which levels of random effects to include in
     this  calculation. 'extract.lme.cov' forms the full matrix
     explicitly: 'extract.lme.cov2' tries to be more economical than
     this.

Usage:

     extract.lme.cov(b,data,start.level=1)
     extract.lme.cov2(b,data,start.level=1)

Arguments:

       b: A fitted model object returned by a call to 'lme'

    data: The data frame/ model frame that was supplied to 'lme'.

start.level: The level of nesting at which to start including random 
          effects in the calculation. This is used to allow smooth
          terms to be estimated as random effects, but treated like
          fixed effects for variance calculations.

Details:

     The random effects, correlation structure and variance structure
     used for a linear mixed model combine to imply a covariance matrix
     for the  response data being modelled. These routines extracts
     that covariance matrix. The process is slightly complicated,
     because different components of the  fitted model object are
     stored in different orders (see function code for  details!).  

     The 'extract.lme.cov' calculation is not optimally efficient,
     since it forms the full matrix, which may in fact be sparse.
     'extract.lme.cov2' is more efficient. If the covariance matrix is
     diagonal, then only the leading diagonal is returned; if it can be
     written as a block diagonal matrix (under some permutation of the
     original data) then a list of matrices defining the non-zero
     blocks is returned along with an index indicating which row of the
     original data each row/column of the block diagonal matrix relates
     to. The block sizes are defined by the coarsest level of grouping
     in the random effect structure.

     'gamm' uses 'extract.lme.cov2'.

     'extract.lme.cov' does not currently deal with the situation in
     which the grouping factors for a correlation structure are finer
     than those for the random effects. 'extract.lme.cov2' does deal
     with this situation.

Value:

     For 'extract.lme.cov' an estimated covariance matrix.

     For 'extract.lme.cov2' a list containing the estimated covariance
     matrix and an indexing array. The covariance matrix is stored as
     the elements on the leading diagonal, a list of the matrices
     defining a block diagonal matrix, or a full matrix if the previous
     two options are not possible.

Author(s):

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

References:

     For 'lme' see:

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

     For details of how GAMMs are set up here for estimation using
     'lme' see:

     Wood, S.N. (2006) Low rank scale invariant tensor product smooths
     for Generalized Additive Mixed Models. Biometrics 62(4):1025-1036

     or 

     Wood S.N. (2006) Generalized Additive Models: An Introduction with
     R. Chapman and Hall/CRC Press.

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

See Also:

     'gamm', 'formXtViX'

Examples:

     library(nlme)
     data(Rail)
     b <- lme(travel~1,Rail,~1|Rail)
     extract.lme.cov(b,Rail)

