\HeaderA{corAR1}{AR(1) Correlation Structure}{corAR1}
\keyword{models}{corAR1}
\begin{Description}\relax
This function is a constructor for the \code{corAR1} class,
representing an autocorrelation structure of order 1. Objects
created using this constructor must later be initialized using the
appropriate \code{Initialize} method.
\end{Description}
\begin{Usage}
\begin{verbatim}
corAR1(value, form, fixed)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{value}] the value of the lag 1 autocorrelation, which must be
between -1 and 1. Defaults to 0 (no autocorrelation).
\item[\code{form}] a one sided formula of the form \code{\textasciitilde{} t}, or \code{\textasciitilde{} t |
     g}, specifying a time covariate \code{t} and,  optionally, a
grouping factor \code{g}. A covariate for this correlation structure
must be integer valued. When a grouping factor is present in
\code{form}, the correlation structure is assumed to apply only
to observations within the same grouping level; observations with
different grouping levels are assumed to be uncorrelated. Defaults to
\code{\textasciitilde{} 1}, which corresponds to using the order of the observations
in the data as a covariate, and no groups.
\item[\code{fixed}] an optional logical value indicating whether the
coefficients should be allowed to vary in the optimization, or kept
fixed at their initial value. Defaults to \code{FALSE}, in which case
the coefficients are allowed to vary.
\end{ldescription}
\end{Arguments}
\begin{Value}
an object of class \code{corAR1}, representing an autocorrelation
structure of order 1.
\end{Value}
\begin{Author}\relax
Jose Pinheiro \email{Jose.Pinheiro@pharma.novartis.com} and Douglas Bates \email{bates@stat.wisc.edu}
\end{Author}
\begin{References}\relax
Box, G.E.P., Jenkins, G.M., and Reinsel G.C. (1994) "Time Series
Analysis: Forecasting and Control", 3rd Edition, Holden-Day.

Pinheiro, J.C., and Bates, D.M. (2000) "Mixed-Effects Models
in S and S-PLUS", Springer, esp. pp. 235, 397.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{ACF.lme}{ACF.lme}},
\code{\LinkA{corARMA}{corARMA}}, 
\code{\LinkA{corClasses}{corClasses}},
\code{\LinkA{Dim.corSpatial}{Dim.corSpatial}}, 
\code{\LinkA{Initialize.corStruct}{Initialize.corStruct}}, 
\code{\LinkA{summary.corStruct}{summary.corStruct}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## covariate is observation order and grouping factor is Mare
cs1 <- corAR1(0.2, form = ~ 1 | Mare)

# Pinheiro and Bates, p. 236
cs1AR1 <- corAR1(0.8, form = ~ 1 | Subject)
cs1AR1. <- Initialize(cs1AR1, data = Orthodont)
corMatrix(cs1AR1.)

# Pinheiro and Bates, p. 240
fm1Ovar.lme <- lme(follicles ~ sin(2*pi*Time) + cos(2*pi*Time),
                   data = Ovary, random = pdDiag(~sin(2*pi*Time)))
fm2Ovar.lme <- update(fm1Ovar.lme, correlation = corAR1())

# Pinheiro and Bates, pp. 255-258:  use in gls
fm1Dial.gls <-
  gls(rate ~(pressure + I(pressure^2) + I(pressure^3) + I(pressure^4))*QB,
      Dialyzer)
fm2Dial.gls <- update(fm1Dial.gls,
                 weights = varPower(form = ~ pressure))
fm3Dial.gls <- update(fm2Dial.gls,
                    corr = corAR1(0.771, form = ~ 1 | Subject))

# Pinheiro and Bates use in nlme:  
# from p. 240 needed on p. 396
fm1Ovar.lme <- lme(follicles ~ sin(2*pi*Time) + cos(2*pi*Time),
                   data = Ovary, random = pdDiag(~sin(2*pi*Time)))
fm5Ovar.lme <- update(fm1Ovar.lme,
                corr = corARMA(p = 1, q = 1))
# p. 396
fm1Ovar.nlme <- nlme(follicles~
     A+B*sin(2*pi*w*Time)+C*cos(2*pi*w*Time),
   data=Ovary, fixed=A+B+C+w~1,
   random=pdDiag(A+B+w~1),
   start=c(fixef(fm5Ovar.lme), 1) )
# p. 397
fm2Ovar.nlme <- update(fm1Ovar.nlme,
         corr=corAR1(0.311) )
\end{ExampleCode}
\end{Examples}

