extract.lme.cov             package:mgcv             R Documentation

_E_x_t_r_a_c_t _t_h_e _d_a_t_a _c_o_v_a_r_i_a_n_c_e _m_a_t_r_i_x _f_r_o_m _a_n _l_m_e _o_b_j_e_c_t

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

       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.

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

     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.

_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:

     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/>

_S_e_e _A_l_s_o:

     'gamm', 'formXtViX'

_E_x_a_m_p_l_e_s:

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