\Header{extract.lme.cov}{Extract the data covariance matrix from an lme object}
\keyword{models}{extract.lme.cov}
\keyword{smooth}{extract.lme.cov}
\keyword{regression}{extract.lme.cov}
\begin{Description}\relax
This is a service routine for \code{\Link{gamm}}. It extracts 
the estimated covariance matrix of the data from an \code{lme} object, allowing the 
user control about which levels of random effects to include in this 
calculation.
\end{Description}
\begin{Usage}
\begin{verbatim}
extract.lme.cov(b,data,start.level=1)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{b}] A fitted model object returned by a call to \code{\Link{lme}}
\item[\code{data}] The data frame/ model frame that was supplied to
\code{\Link{lme}}.
\item[\code{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.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
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. This routine 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 calculation is not optimally efficient, since it forms the full matrix,
which may in fact be sparse. In applications in which the main objective is
to allow non-independent `errors' in GAMs this is unlikely to cause great 
computational losses.
\end{Details}
\begin{Value}
An estimated covariance matrix.
\end{Value}
\begin{Author}\relax
Simon N. Wood \email{simon@stats.gla.ac.uk}
\end{Author}
\begin{References}\relax
For \code{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 \code{lme} see:

Wood, S.N. (manuscript) Tensor product smooth interaction terms in 
Generalized Additive Mixed Models.


\url{http://www.stats.gla.ac.uk/~simon/}
\end{References}
\begin{SeeAlso}\relax
\code{\Link{gamm}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
library(nlme)
data(Rail)
b <- lme(travel~1,Rail,~1|Rail)
extract.lme.cov(b,Rail)
\end{ExampleCode}
\end{Examples}

