Variogram.lme              package:nlme              R Documentation

_C_a_l_c_u_l_a_t_e _S_e_m_i-_v_a_r_i_o_g_r_a_m _f_o_r _R_e_s_i_d_u_a_l_s _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 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.

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

  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.

_V_a_l_u_e:

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

_A_u_t_h_o_r(_s):

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

_R_e_f_e_r_e_n_c_e_s:

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

_S_e_e _A_l_s_o:

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

_E_x_a_m_p_l_e_s:

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

