addterm                 package:MASS                 R Documentation

Try All One-Term Additions to a Model

Description:

     Try fitting all models that differ from the current model by
     adding a single term from those supplied, maintaining marginality.

     This function is generic; there exist methods for classes 'lm' and
     'glm' and the default method will work for many other classes.

Usage:

     addterm(object, ...)

     ## Default S3 method:
     addterm(object, scope, scale = 0, test = c("none", "Chisq"),
             k = 2, sorted = FALSE, trace = FALSE, ...)
     ## S3 method for class 'lm':
     addterm(object, scope, scale = 0, test = c("none", "Chisq", "F"),
             k = 2, sorted = FALSE, ...)
     ## S3 method for class 'glm':
     addterm(object, scope, scale = 0, test = c("none", "Chisq", "F"),
             k = 2, sorted = FALSE, trace = FALSE, ...)

Arguments:

  object: An object fitted by some model-fitting function. 

   scope: a formula specifying a maximal model which should include the
          current one. All additional terms in the maximal model with
          all marginal terms in the original model are tried. 

   scale: used in the definition of the AIC statistic for selecting the
          models, currently only for 'lm', 'aov' and 'glm' models.
          Specifying 'scale' asserts that the residual standard error
          or dispersion is known. 

    test: should the results include a test statistic relative to the
          original model?  The F test is only appropriate for 'lm' and
          'aov' models, and perhaps for some over-dispersed 'glm'
          models. The Chisq test can be an exact test ('lm' models with
          known scale) or a likelihood-ratio test depending on the
          method. 

       k: the multiple of the number of degrees of freedom used for the
          penalty. Only 'k=2' gives the genuine AIC: 'k = log(n)' is
          sometimes referred to as BIC or SBC. 

  sorted: should the results be sorted on the value of AIC? 

   trace: if 'TRUE' additional information may be given on the fits as
          they are tried. 

     ...: arguments passed to or from other methods. 

Details:

     The definition of AIC is only up to an additive constant: when
     appropriate ('lm' models with specified scale) the constant is
     taken to be that used in Mallows' Cp statistic and the results are
     labelled accordingly.

Value:

     A table of class '"anova"' containing at least columns for the
     change in degrees of freedom and AIC (or Cp) for the models. Some
     methods will give further information, for example sums of
     squares, deviances, log-likelihoods and test statistics.

References:

     Venables, W. N. and Ripley, B. D. (2002) _Modern Applied
     Statistics with S._ Fourth edition.  Springer.

See Also:

     'dropterm', 'stepAIC'

Examples:

     quine.hi <- aov(log(Days + 2.5) ~ .^4, quine)
     quine.lo <- aov(log(Days+2.5) ~ 1, quine)
     addterm(quine.lo, quine.hi, test="F")

     house.glm0 <- glm(Freq ~ Infl*Type*Cont + Sat, family=poisson,
                        data=housing)
     addterm(house.glm0, ~. + Sat:(Infl+Type+Cont), test="Chisq")
     house.glm1 <- update(house.glm0, . ~ . + Sat*(Infl+Type+Cont))
     addterm(house.glm1, ~. + Sat:(Infl+Type+Cont)^2, test = "Chisq")

