ACF.gls                 package:nlme                 R Documentation

Autocorrelation Function for gls Residuals

Description:

     This method function calculates the empirical autocorrelation
     function for the residuals from a 'gls' fit. If a grouping
     variable is specified in 'form', the autocorrelation values are
     calculated using pairs of residuals within the same group;
     otherwise all possible residual pairs are used. The
     autocorrelation function is useful for investigating serial
     correlation models for equally spaced data.

Usage:

     ## S3 method for class 'gls':
     ACF(object, maxLag, resType, form, na.action, ...)

Arguments:

  object: an object inheriting from class 'gls', representing a
          generalized least squares fitted  model.

  maxLag: an optional integer giving the maximum lag for which the
          autocorrelation should be calculated. Defaults to maximum lag
          in the residuals.

 resType: an optional character string specifying the type of residuals
          to be used. If '"response"', the "raw" residuals (observed -
          fitted) are used; else, if '"pearson"', the standardized
          residuals (raw residuals divided by the corresponding
          standard errors) are used; else, if '"normalized"', the
          normalized residuals (standardized residuals pre-multiplied
          by the inverse square-root factor of the estimated error
          correlation matrix) are used. Partial matching of arguments
          is used, so only the first character needs to be provided.
          Defaults to '"pearson"'.

    form: an optional one sided formula of the form '~ t', or '~ t |
          g', specifying a time covariate 't' and,  optionally, a
          grouping factor 'g'. The time covariate must be integer
          valued. When a grouping factor is present in  'form', the
          autocorrelations are calculated using residual pairs within
          the same group. Defaults to '~ 1', which corresponds to using
          the order of the observations in the data as a covariate, and
          no groups.

na.action: a function that indicates what should happen when the data
          contain 'NA's.  The default action ('na.fail') causes
          'ACF.gls' to print an error message and terminate if there
          are any incomplete observations.

     ...: some methods for this generic require additional arguments.

Value:

     a data frame with columns 'lag' and 'ACF' representing,
     respectively, the lag between residuals within a pair and the
     corresponding empirical autocorrelation. The returned value
     inherits from class 'ACF'.

Author(s):

     Jose Pinheiro Jose.Pinheiro@pharma.novartis.com and Douglas Bates
     bates@stat.wisc.edu

References:

     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.

See Also:

     'ACF.gls', 'plot.ACF'

Examples:

     fm1 <- gls(follicles ~ sin(2*pi*Time) + cos(2*pi*Time), Ovary)
     ACF(fm1, form = ~ 1 | Mare)

     # Pinheiro and Bates, p. 255-257
     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))

     ACF(fm2Dial.gls, form = ~ 1 | Subject)

