residuals.lme              package:nlme              R Documentation

Extract lme Residuals

Description:

     The residuals at level i are obtained by subtracting the fitted
     levels at that level from the response vector (and dividing by the
     estimated within-group standard error, if 'type="pearson"'). The
     fitted values at level i are obtained by adding together the
     population fitted values (based only on the fixed effects
     estimates) and the estimated contributions of the random effects
     to the fitted values at grouping levels less or equal to i.

Usage:

     ## S3 method for class 'lme':
     residuals(object, level, type, asList, ...)

Arguments:

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

   level: an optional integer vector giving the level(s) of grouping to
          be used in extracting the residuals from 'object'. Level
          values increase from outermost to innermost grouping, with
          level zero corresponding to the population residuals.
          Defaults to the highest or innermost level of grouping.

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

  asList: an optional logical value. If 'TRUE' and a single value is
          given in 'level', the returned object is a list with the
          residuals split by groups; else the returned value is either
          a vector or a data frame, according to the length of 'level'.
          Defaults to 'FALSE'.

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

Value:

     if a single level of grouping is specified in 'level', the
     returned value is either a list with the residuals split by groups
     ('asList = TRUE') or a vector with the residuals ('asList =
     FALSE'); else, when multiple grouping levels are specified in
     'level', the returned object is a data frame with columns given by
     the residuals at different levels and the grouping factors.

Author(s):

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

References:

     Bates, D.M. and Pinheiro, J.C. (1998) "Computational methods for
     multilevel models" available in PostScript or PDF formats at
     http://franz.stat.wisc.edu/pub/NLME/

See Also:

     'lme', 'fitted.lme'

Examples:

     data(Orthodont)
     fm1 <- lme(distance ~ age + Sex, data = Orthodont, random = ~ 1)
     residuals(fm1, level = 0:1)

