augPred                 package:nlme                 R Documentation

Augmented Predictions

Description:

     Predicted values are obtained at the specified values of
     'primary'. If 'object' has a grouping structure (i.e.
     'getGroups(object)' is not 'NULL'), predicted values are obtained
     for each group. If 'level' has more than one element, predictions
     are obtained for each level of the 'max(level)' grouping factor.
     If other covariates besides 'primary' are used in the prediction
     model, their average (numeric covariates) or most frequent value
     (categorical covariates) are used to obtain the predicted values.
     The original observations are also included in the returned
     object.

Usage:

     augPred(object, primary, minimum, maximum, length.out, ...)

Arguments:

  object: a fitted model object from which predictions can be
          extracted, using a 'predict' method.

 primary: an optional one-sided formula specifying the primary
          covariate to be used to generate the augmented predictions.
          By default, if a  covariate can be extracted from the data
          used to generate 'object' (using 'getCovariate'), it will be
          used as 'primary'.

 minimum: an optional lower limit for the primary covariate. Defaults
          to 'min(primary)'.

 maximum: an optional upper limit for the primary covariate. Defaults
          to 'max(primary)'.

length.out: an optional integer with the number of primary covariate
          values at which to evaluate the predictions. Defaults to 51.

     ...: some methods for the generic may require additional
          arguments.

Value:

     a data frame with four columns representing, respectively, the
     values of the primary covariate, the groups (if 'object' does not
     have a grouping structure, all elements will be '1'), the
     predicted or observed values, and the type of value in the third
     column: 'original' for the observed values and 'predicted' (single
     or no grouping factor) or 'predict.groupVar' (multiple levels of
     grouping), with 'groupVar' replaced by the actual grouping
     variable name ('fixed' is used for population predictions). The
     returned object inherits from class 'augPred'.

Note:

     This function is generic; method functions can be written to
     handle specific classes of objects. Classes which already have
     methods for this function include: 'gls', 'lme', and 'lmList'.

Author(s):

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

References:

     Pinheiro, J. C. and Bates, D. M. (2000), _Mixed-Effects Models in
     S and S-PLUS_, Springer, New York.

See Also:

     'plot.augPred', 'getGroups', 'predict'

Examples:

     fm1 <- lme(Orthodont, random = ~1)
     augPred(fm1, length.out = 2, level = c(0,1))

