pairs.lme                package:nlme                R Documentation

Pairs Plot of an lme 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. The expression on the right hand side of the formula,
     before a '|' operator, must evaluate to a data frame with at least
     two columns. If the data frame has two columns, a scatter plot of
     the two variables is displayed (the Trellis function 'xyplot' is
     used). Otherwise, if more than two columns are present, a scatter
     plot matrix with pairwise scatter plots of the columns in the data
     frame is displayed (the Trellis function 'splom' is used).

Usage:

     ## S3 method for class 'lme':
     pairs(x, form, label, id, idLabels, grid, ...)

Arguments:

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

    form: an optional one-sided 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. The expression
          on the right hand side of 'form', and to the left of the '|'
          operator, must evaluate to a data frame with at least two
          columns. Default is '~ coef(.) ', corresponding to a pairs
          plot of the coefficients evaluated at the innermost level of
          nesting.

   label: an optional character vector of labels for the variables in
          the pairs plot.

      id: an optional numeric value, or one-sided formula. If given as
          a value, it is used as a significance level for an outlier
          test based on the Mahalanobis distances of the estimated
          random effects. Groups with random effects distances greater
          than the 1-value percentile of the appropriate chi-square
          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 points in the plot. If missing, no points
          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
          points 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
          points. Default is the innermost grouping factor.  

    grid: an optional logical value indicating whether a grid should be
          added to plot. Default is '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', 'pairs.compareFits',  'pairs.lmList',  'xyplot', 'splom'

Examples:

     fm1 <- lme(distance ~ age, Orthodont, random = ~ age | Subject)
     # scatter plot of coefficients by gender, identifying unusual subjects
     pairs(fm1, ~coef(., augFrame = TRUE) | Sex, id = 0.1, adj = -0.5)    
     # scatter plot of estimated random effects
     ## Not run: 
     pairs(fm1, ~ranef(.))
     ## End(Not run)

