anova.lme                package:nlme                R Documentation

Compare Likelihoods of Fitted Objects

Description:

     When only one fitted model object is present, a data frame with
     the sums of squares, numerator degrees of freedom, denominator
     degrees of freedom, F-values, and P-values for Wald tests for the
     terms in the model (when 'Terms' and 'L' are 'NULL'), a
     combination of model terms (when 'Terms' in not 'NULL'), or linear
     combinations of the model coefficients (when 'L' is not 'NULL').
     Otherwise, when multiple fitted objects are being compared, a data
     frame with the degrees of freedom, the (restricted)
     log-likelihood, the Akaike Information Criterion (AIC), and the
     Bayesian Information Criterion (BIC) of each object is returned.
     If 'test=TRUE', whenever two consecutive  objects have different
     number of degrees of freedom, a likelihood ratio statistic, with
     the associated p-value is included in the returned data frame.

Usage:

     ## S3 method for class 'lme':
     anova(object, ..., test, type, adjustSigma, Terms, L, verbose)
     ## S3 method for class 'anova.lme':
     print(x, verbose, ...)

Arguments:

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

     ...: other optional fitted model objects inheriting from classes
          'gls', 'gnls', 'lm', 'lme', 'lmList', 'nlme', 'nlsList', or
          'nls'.

    test: an optional logical value controlling whether likelihood
          ratio tests should be used to compare the fitted models
          represented by 'object' and the objects in '...'. Defaults to
          'TRUE'.

    type: an optional character string specifying the type of sum of
          squares to be used in F-tests for the terms in the model. If 
          '"sequential"', the sequential sum of squares obtained by
          including the terms in the order they appear in the model is
          used; else, if '"marginal"', the marginal sum of squares
          obtained by deleting a term from the model at a time is used.
          This argument is only used when a single fitted object is
          passed to the function. Partial matching of arguments is
          used, so only the first character needs to be provided.
          Defaults to '"sequential"'.

adjustSigma: an optional logical value. If 'TRUE' and the estimation
          method used to obtain 'object' was maximum likelihood, the
          residual standard error is multiplied by sqrt(nobs/(nobs -
          npar)), converting it to a REML-like estimate. This argument
          is only used when a single fitted object is passed to the
          function. Default is 'TRUE'.

   Terms: an optional integer or character vector specifying which
          terms in the model should be jointly tested to be zero using
          a Wald F-test. If given as a character vector, its elements
          must correspond to term names; else, if given as an integer
          vector, its elements must correspond to the order in which
          terms are included in the model. This argument is only used
          when a single fitted object is passed to the function.
          Default is 'NULL'.

       L: an optional numeric vector or array specifying linear
          combinations of the coefficients in the model that should be
          tested to be zero. If given as an array, its rows define the
          linear combinations to be tested. If names are assigned to
          the vector elements (array columns), they must correspond to
          coefficients names and will be used to map the linear
          combination(s) to the coefficients; else, if no names are
          available, the vector elements (array columns) are assumed in
          the same order as the coefficients appear in the model. This
          argument is only used when a single fitted object is passed
          to the function. Default is 'NULL'.

       x: an object inheriting from class 'anova.lme'

 verbose: an optional logical value. If 'TRUE', the calling sequences
          for each fitted model object are printed with the rest of the
          output, being omitted if 'verbose = FALSE'. Defaults to
          'FALSE'.

Value:

     a data frame inheriting from class 'anova.lme'.

Note:

     Likelihood comparisons are not meaningful for objects fit using
     restricted maximum likelihood and with different fixed effects.

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.

See Also:

     'gls', 'gnls', 'nlme', 'lme', 'AIC', 'BIC', 'print.anova.lme',
     'logLik.lme',

Examples:

     fm1 <- lme(distance ~ age, Orthodont, random = ~ age | Subject)
     anova(fm1)
     fm2 <- update(fm1, random = pdDiag(~age))
     anova(fm1, fm2)

     # Pinheiro and Bates, pp. 251-254
     fm1Orth.gls <- gls(distance ~ Sex * I(age - 11), Orthodont,
                 correlation = corSymm(form = ~ 1 | Subject),
                 weights = varIdent(form = ~ 1 | age))
     fm2Orth.gls <- update(fm1Orth.gls,
                     corr = corCompSymm(form = ~ 1 | Subject))
     # anova.gls
     anova(fm1Orth.gls, fm2Orth.gls)
     fm3Orth.gls <- update(fm2Orth.gls, weights = NULL)
     # anova.gls
     anova(fm2Orth.gls, fm3Orth.gls)
     fm4Orth.gls <- update(fm3Orth.gls,
                      weights = varIdent(form = ~ 1 | Sex))
     # anova.gls
     anova(fm3Orth.gls, fm4Orth.gls)
     # not in book but needed for the following command
     fm3Orth.lme <-
         lme(distance~Sex*I(age-11), data = Orthodont,
             random = ~ I(age-11) | Subject,
             weights = varIdent(form = ~ 1 | Sex))
     # anova.lme to compare an "lme" object with a "gls" object 
     anova(fm3Orth.lme, fm4Orth.gls, test = FALSE)

     # Pinheiro and Bates, pp. 222-225
     options(contrasts = c("contr.treatment", "contr.poly"))
     fm1BW.lme <- lme(weight ~ Time * Diet, BodyWeight,
                        random = ~ Time)
     fm2BW.lme <- update(fm1BW.lme, weights = varPower())
     # Test a specific contrast
     anova(fm2BW.lme, L = c("Time:Diet2" = 1, "Time:Diet3" = -1))

     fm1Theo.lis <- nlsList(
          conc ~ SSfol(Dose, Time, lKe, lKa, lCl), data=Theoph)
     fm1Theo.lis

     # Pinheiro and Bates, pp. 352-365
     fm1Theo.lis <- nlsList(
          conc ~ SSfol(Dose, Time, lKe, lKa, lCl), data=Theoph)
     fm1Theo.nlme <- nlme(fm1Theo.lis)
     fm2Theo.nlme <- update(fm1Theo.nlme,
        random=pdDiag(lKe+lKa+lCl~1) )
     fm3Theo.nlme <- update(fm2Theo.nlme,
        random=pdDiag(lKa+lCl~1) )

     # anova comparing 3 models
     anova(fm1Theo.nlme, fm3Theo.nlme, fm2Theo.nlme)

