Variogram.lme              package:nlme              R Documentation

Calculate Semi-variogram for Residuals from an lme Object

Description:

     This method function calculates the semi-variogram for the
     within-group residuals from an 'lme' fit. The semi-variogram
     values are calculated for pairs of residuals within the same
     group. If 'collapse' is different from '"none"', the individual
     semi-variogram values are collapsed using either a robust
     estimator ('robust = TRUE') defined in Cressie (1993), or the
     average of the values within the same distance interval. The
     semi-variogram is useful for modeling the error term correlation
     structure.

Usage:

     ## S3 method for class 'lme':
     Variogram(object, distance, form, resType, data,
            na.action, maxDist, length.out, collapse, nint, breaks,
            robust, metric, ...)

Arguments:

  object: an object inheriting from class 'lme', representing a fitted
          linear mixed-effects model.

distance: an optional numeric vector with the distances between
          residual pairs. If a grouping variable is present, only the
          distances between residual pairs within the same group should
          be given. If missing, the distances are calculated based on
          the values of the arguments 'form', 'data', and 'metric',
          unless 'object' includes a 'corSpatial' element, in which
          case the associated covariate (obtained with the
          'getCovariate' method) is used.

    form: an optional one-sided formula specifying the covariate(s) to
          be used for calculating the distances between residual pairs
          and, optionally, a grouping factor for partitioning the
          residuals (which must appear to the right of a '|' operator
          in 'form'). Default is '~1', implying that the observation 
          order within the groups is used to obtain the distances.

 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"'.

    data: an optional data frame in which to interpret the variables in
          'form'. By default, the same data used to fit 'object' is
          used.

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

 maxDist: an optional numeric value for the maximum distance used for
          calculating the semi-variogram between two residuals. By
          default all residual pairs are included.

length.out: an optional integer value. When 'object' includes a
          'corSpatial' element, its semi-variogram values are
          calculated and this argument is used as the 'length.out'
          argument to the corresponding 'Variogram' method. Defaults to
          '50'.

collapse: an optional character string specifying the type of
          collapsing to be applied to the individual semi-variogram
          values. If equal to '"quantiles"', the semi-variogram values
          are split according to quantiles of the distance
          distribution, with equal number of observations per group,
          with possibly varying distance interval lengths. Else, if
          '"fixed"', the semi-variogram values are divided according to
          distance intervals of equal lengths, with possibly different
          number of observations per interval. Else, if '"none"', no
          collapsing is used and the individual semi-variogram values
          are returned. Defaults to '"quantiles"'.

    nint: an optional integer with the number of intervals to be used
          when collapsing the semi-variogram values. Defaults to '20'.

  robust: an optional logical value specifying if a robust
          semi-variogram estimator should be used when collapsing the
          individual values. If 'TRUE' the robust estimator is used.
          Defaults to 'FALSE'.

  breaks: an optional numeric vector with the breakpoints for the
          distance intervals to be used in collapsing the
          semi-variogram values. If not missing, the option specified
          in 'collapse' is ignored.

  metric: an optional character string specifying the distance metric
          to be used. The currently available options are '"euclidean"'
          for the root sum-of-squares of distances; '"maximum"' for the
          maximum difference; and '"manhattan"' for the sum of the
          absolute differences. Partial matching of arguments is used,
          so only the first three characters need to be provided.
          Defaults to '"euclidean"'.

     ...: some methods for this generic require additional arguments. 
          None are used in this method.

Value:

     a data frame with columns 'variog' and 'dist' representing,
     respectively, the semi-variogram values and the corresponding
     distances. If the semi-variogram values are collapsed, an extra
     column, 'n.pairs', with the number of residual pairs used in each
     semi-variogram calculation, is included in the returned data
     frame. If 'object' includes a 'corSpatial' element, a data frame
     with its corresponding semi-variogram is included in the returned
     value, as an attribute '"modelVariog"'. The returned value
     inherits from class 'Variogram'.

Author(s):

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

References:

     Cressie, N.A.C. (1993), "Statistics for Spatial Data", J. Wiley &
     Sons.

See Also:

     'lme', 'Variogram', 'Variogram.default', 'Variogram.gls',
     'plot.Variogram'

Examples:

     fm1 <- lme(weight ~ Time * Diet, data=BodyWeight, ~ Time | Rat)
     Variogram(fm1, form = ~ Time | Rat, nint = 10, robust = TRUE)

