

   AAuuggmmeenntteedd PPrreeddiiccttiioonnss

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

   AArrgguummeennttss::

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

    primary: an optional one-sided formula specifying the pri-
             mary covariate to be used to generate the aug-
             mented 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 predic-
             tions. Defaults to 51.

      level: an optional integer vector specifying the desired
             prediction levels. Levels increase from outermost
             to innermost grouping, with level 0 representing
             the population (fixed effects) predictions.
             Defaults to the innermost level.

        ...: some methods for the generic may require addi-
             tional arguments.

   DDeessccrriippttiioonn::

        Predicted values are obtained at the specified values
        of `primary'. If `object' has a grouping strutcure
        (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 fre-
        quent value (categorical covariates) are used to obtain
        the predicted values. The original observations are
        also included in the returned object.

   VVaalluuee::

        a data frame with four columns representing, respec-
        tively, 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 val-
        ues, and the type of value in the third column: `origi-
        nal' 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 pop-
        ulation predictions). The returned object inherits from
        class `augPred'.

   NNoottee::

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

   AAuutthhoorr((ss))::

        Jose Pinheiro and Douglas Bates

   SSeeee AAllssoo::

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

   EExxaammpplleess::

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

