plot.lme                package:nlme                R Documentation

Plot an lme or nls object

Description:

     Diagnostic plots for the linear mixed-effects fit are obtained.
     The 'form' argument gives considerable flexibility in the type of
     plot specification. A conditioning expression (on the right side
     of a '|' operator) always implies that different panels are used
     for each level of the conditioning factor, according to a Trellis
     display. If 'form' is a one-sided formula, histograms of the
     variable on the right hand side of the formula, before a '|'
     operator, are displayed (the Trellis function 'histogram' is
     used). If 'form' is two-sided and both its left and right hand
     side variables are numeric, scatter plots are displayed (the
     Trellis function 'xyplot' is used). Finally, if 'form' is
     two-sided and its left had side variable is a factor, box-plots of
     the right hand side variable by the levels of the left hand side
     variable are displayed (the Trellis function  'bwplot' is used).

Usage:

     ## S3 method for class 'lme':
     plot(x, form, abline, id, idLabels, idResType, grid, ...)
     ## S3 method for class 'nls':
     plot(x, form, abline, id, idLabels, idResType, grid, ...)

Arguments:

       x: an object inheriting from class 'lme', representing a fitted
          linear mixed-effects model, or from 'nls', representing an
          fitted nonlinear least squares model.

    form: an optional formula specifying the desired type of plot. Any
          variable present in the original data frame used to obtain
          'x' can be referenced. In addition, 'x' itself can be
          referenced in the formula using the symbol '"."'. Conditional
          expressions on the right of a '|' operator can be used to
          define separate panels in a Trellis display. Default is
          'resid(., type = "p") ~ fitted(.) ', corresponding to a plot
          of the standardized residuals versus fitted values, both
          evaluated at the innermost level of nesting.

  abline: an optional numeric value, or numeric vector of length two.
          If given as a single value, a horizontal line will be added
          to the plot at that coordinate; else, if given as a vector,
          its values are used as the intercept and slope for a line
          added to the plot. If missing, no lines are added to the
          plot.

      id: an optional numeric value, or one-sided formula. If given as
          a value, it is used as a significance level for a two-sided
          outlier test for the standardized, or normalized residuals.
          Observations with absolute standardized (normalized)
          residuals greater than the 1 - value/2 quantile of the
          standard normal distribution are identified in the plot using
          'idLabels'. If given as a one-sided formula, its right hand
          side must evaluate to a  logical, integer, or character
          vector which is used to identify observations in the plot. If
          missing, no observations are identified.

idLabels: an optional vector, or one-sided formula. If given as a
          vector, it is converted to character and used to label the
          observations identified according to 'id'. If given as a
          one-sided formula, its right hand side must evaluate to a
          vector which is converted to character and used to label the
          identified observations. Default is the innermost grouping
          factor.

idResType: an optional character string specifying the type of
          residuals to be used in identifying outliers, when 'id' is a
          numeric value. 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"'.

    grid: an optional logical value indicating whether a grid should be
          added to plot. Default depends on the type of Trellis plot
          used: if 'xyplot' defaults to 'TRUE', else defaults to
          'FALSE'.

     ...: optional arguments passed to the Trellis plot function.

Value:

     a diagnostic Trellis plot.

Author(s):

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

See Also:

     'lme', 'xyplot', 'bwplot', 'histogram'

Examples:

     fm1 <- lme(distance ~ age, Orthodont, random = ~ age | Subject)
     # standardized residuals versus fitted values by gender
     plot(fm1, resid(., type = "p") ~ fitted(.) | Sex, abline = 0)
     # box-plots of residuals by Subject
     plot(fm1, Subject ~ resid(.))
     # observed versus fitted values by Subject
     plot(fm1, distance ~ fitted(.) | Subject, abline = c(0,1))

