plot.ranef.lmList            package:nlme            R Documentation

Plot a ranef.lmList Object

Description:

     If 'form' is missing, or is given as a one-sided formula, a
     Trellis dot-plot of the random effects is generated, with a
     different panel for each random effect (coefficient). Rows in the
     dot-plot are determined by the 'form' argument (if not missing) or
     by the row names of the random effects (coefficients). If a single
     factor is specified in 'form', its levels determine the dot-plot
     rows (with possibly multiple dots per row); otherwise, if 'form'
     specifies a crossing of factors, the dot-plot rows are determined
     by all combinations of the levels of the individual factors in the
      formula. The Trellis function 'dotplot' is used in this method
     function.

     If 'form' is a two-sided formula, a Trellis display is generated,
     with a different panel for each variable listed in the right hand
     side of 'form'. Scatter plots are generated for numeric variables
     and boxplots are generated for categorical ('factor' or 'ordered')
     variables.

Usage:

     ## S3 method for class 'ranef.lmList':
     plot(x, form, grid, control, ...)

Arguments:

       x: an object inheriting from class 'ranef.lmList', representing
          the estimated coefficients or estimated random effects for
          the 'lmList' object from which it was produced. 

    form: an optional formula specifying the desired type of plot. If
          given as a one-sided formula, a 'dotplot' of the estimated
          random effects (coefficients) grouped according to all
          combinations of the levels of the factors named in 'form' is
          returned. Single factors ('~g') or crossed factors ('~g1*g2')
          are allowed. If given as a two-sided formula, the left hand
          side must be a single random effects (coefficient) and the
          right hand side is formed by covariates in 'x' separated by
          '+'. A Trellis display of the random effect (coefficient)
          versus the named covariates is returned in this case. Default
          is 'NULL', in which case  the row names of the random effects
          (coefficients) are used.

    grid: an optional logical value indicating whether a grid should be
          added to plot. Only applies to plots associated with
          two-sided formulas in 'form'. Default is 'FALSE'.

 control: an optional list with control values for the plot, when
          'form' is given as a two-sided formula. The control values
          are referenced by name in the 'control' list and  only the
          ones to be modified from the default need to be specified.
          Available values include: 'drawLine', a logical value
          indicating whether a 'loess' smoother should be added to the
          scatter plots and a line connecting the medians should be
          added to the boxplots (default is 'TRUE'); 'span.loess', used
          as the 'span' argument in the call to 'panel.loess' (default
          is '2/3'); 'degree.loess', used as the 'degree' argument in
          the call to 'panel.loess' (default is '1'); 'cex.axis', the
          character expansion factor for the x-axis (default is '0.8');
          'srt.axis', the rotation factor for the x-axis (default is
          '0'); and 'mgp.axis', the margin parameters for the x-axis
          (default is 'c(2, 0.5, 0)').

     ...: optional arguments passed to the Trellis 'dotplot' function. 

Value:

     a Trellis plot of the estimated random-effects (coefficients)
     versus covariates, or groups.

Author(s):

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

See Also:

     'lmList', 'dotplot'

Examples:

     fm1 <- lmList(distance ~ age | Subject, Orthodont)
     plot(ranef(fm1))
     fm1RE <- ranef(fm1, aug = TRUE)
     plot(fm1RE, form = ~ Sex)
     ## Not run: 
     plot(fm1RE, form = age ~ Sex)
     ## End(Not run)

