glht                package:multcomp                R Documentation

_G_e_n_e_r_a_l _L_i_n_e_a_r _H_y_p_o_t_h_e_s_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     General linear hypotheses and multiple comparisons  for parametric
     models, including generalized linear models,  linear mixed effects
     models, and survival models.

_U_s_a_g_e:

     ## S3 method for class 'matrix':
     glht(model, linfct, 
         alternative = c("two.sided", "less", "greater"), 
         rhs = 0, ...)
     ## S3 method for class 'character':
     glht(model, linfct, ...)
     ## S3 method for class 'expression':
     glht(model, linfct, ...)
     ## S3 method for class 'mcp':
     glht(model, linfct, ...)
     mcp(...)

_A_r_g_u_m_e_n_t_s:

   model: a fitted model,  for example an object returned by 'lm', 
          'glm', or 'aov' etc. It is  assumed that 'coef' and  'vcov'
          methods are available for  'model'. For multiple comparisons
          of means, methods 'model.matrix',  'model.frame' and 'terms'
          are expected to be available for 'model' as well.

  linfct: a specification of the linear hypotheses to be tested. 
          Linear functions can be specified by either the matrix of
          coefficients or by symbolic descriptions of  one or more
          linear hypotheses. Multiple comparisons in AN(C)OVA models
          are specified by objects returned from function 'mcp'.

alternative: a character string specifying the alternative  hypothesis,
          must be one of '"two.sided"' (default), '"greater"' or
          '"less"'.  You can specify just the initial letter.

     rhs: an optional numeric vector specifying the  right hand side of
          the hypothesis.

     ...: additional arguments to function 'modelparm' in all 'glht'
          methods. For function 'mcp', multiple comparisons are defined
          by  matrices or symbolic descriptions specifying contrasts of
          factor levels where the arguments correspond to factor names.

_D_e_t_a_i_l_s:

     A general linear hypothesis refers to null hypotheses of the form
     H_0: K theta = m for some parametric model 'model' with parameter
     estimates 'coef(model)'. 

     The null hypothesis is specified by a linear function $K \theta$, 
     the direction of the alternative and the right hand side $m$.
     Here, 'alternative' equal to '"two.sided"' refers to  a null
     hypothesis H_0: K theta = m, whereas '"less"' corresponds to H_0:
     K theta >= m and   '"greater"' refers to  H_0: K theta <= m. The
     right hand side vector $m$ can be defined via the 'rhs' argument.

     The generic method 'glht' dispatches on its second argument
     ('linfct'). There are three ways, and thus methods,  to specify
     linear functions to be tested:

     1) The 'matrix' of coefficients $K$ can be specified directly via
     the 'linfct' argument. In this case, the number of columns of this
     matrix needs to correspond to the number of parameters estimated
     by 'model'. It is assumed that appropriate 'coef' and 'vcov'
     methods are available for 'model' ('modelparm' deals with some
     exceptions). 

     2) A symbolic description, either a 'character' or 'expression'
     vector passed to 'glht' via its 'linfct' argument, can be used to
     define the null hypothesis. A symbolic description must be
     interpretable as a valid R expression consisting of both the left
     and right hand side  of a linear hypothesis. Only the names of
     'coef(model)' must be used as variable names. The alternative is
     given by the direction under the null hypothesis ('=' or '=='
     refer to '"two.sided"', '<=' means '"greater"' and '>=' indicates 
     '"less"'). Numeric vectors of length one are valid values for the
     right hand side.

     3) Multiple comparisons of means are defined by objects of class
     'mcp' as returned by the 'mcp' function. For each factor, which is
     included in 'model'  as independent variable, a contrast matrix or
     a symbolic description of the contrasts can be specified as
     arguments to 'mcp'. A symbolic description may be a 'character' or
     'expression'  where the factor levels are only used as variables
     names. In addition, the 'type' argument to the contrast generating
     function 'contrMat' may serve as a symbolic description of 
     contrasts as well.

     The 'mcp' function must be used with care when defining parameters
     of interest in two-way ANOVA or ANCOVA models. Here, the
     definition of treatment differences (such as Tukey's all-pair
     comparisons or Dunnett's comparison with a control) might be
     problem specific.  Because it is impossible to determine the
     parameters of interest automatically in this case, 'mcp' in
     multcomp version 1.0-0 and higher generates comparisons for the
     main effects only, ignoring covariates and interactions (older
     versions automatically averaged over interaction terms). A warning
     is given. We refer to Hsu (1996), Chapter 7, and Searle (1971),
     Chapter 7.3,  for further discussions and examples on this issue.

     'glht' extracts the number of degrees of freedom for models of
     class 'lm' (via 'modelparm') and the exact multivariate $t$
     distribution is evaluated. For all other models, results rely on
     the normal approximation. Alternatively, the  degrees of freedom
     to be used for the evaluation of multivariate $t$ distributions
     can be given by the additional 'df' argument to 'modelparm'
     specified via '...'.

     'glht' methods return a specification of the null hypothesis H_0:
     K theta = m. The value of the linear function $K \theta$ can be
     extracted using the 'coef' method and the corresponding covariance
     matrix is available from the  'vcov' method. Various simultaneous
     and univariate tests and  confidence intervals are available from
     'summary.glht' and 'confint.glht' methods, respectively.

     A more detailed description of the underlying methodology is
     available from Hothorn et al. (2008).

_V_a_l_u_e:

     An object of class 'glht', more specifically a list with elements 

   model: a fitted model, used in the call to 'glht'

  linfct: the matrix of linear functions

     rhs: the vector of right hand side values m

    coef: the values of the linear functions

    vcov: the covariance matrix of the values of the linear functions

      df: optionally, the degrees of freedom when the exact $t$ 
          distriubtion is used for inference

alternative: a character string specifying the alternative hypothesis

    type: optionally, a character string giving the name of the
          specific procedure

     with 'print', 'summary',  'confint', 'coef' and 'vcov'  methods
     being available. When called with 'linfct' being an 'mcp' object,
     an additional element 'focus' is available storing the names of
     the factors under test.

_R_e_f_e_r_e_n_c_e_s:

     Shayle R. Searle (1971), _Linear Models_. John Wiley & Sons, New
     York.

     Jason C. Hsu (1996), _Multiple Comparisons_. Chapman & Hall,
     London.

     Torsten Hothorn, Frank Bretz and Peter Westfall (2008),
     Simultaneous Inference in General Parametric Models. _Biometrical
     Journal_, *50*(3) (forthcoming); See 'vignette("generalsiminf",
     package = "multcomp")'.

_E_x_a_m_p_l_e_s:

       ### multiple linear model, swiss data
       lmod <- lm(Fertility ~ ., data = swiss)

       ### test of H_0: all regression coefficients are zero 
       ### (ignore intercept)

       ### define coefficients of linear function directly
       K <- diag(length(coef(lmod)))[-1,]
       rownames(K) <- names(coef(lmod))[-1]
       K

       ### set up general linear hypothesis
       glht(lmod, linfct = K)

       ### alternatively, use a symbolic description 
       ### instead of a matrix 
       glht(lmod, linfct = c("Agriculture = 0",
                             "Examination = 0",
                             "Education = 0",
                             "Catholic = 0",
                             "Infant.Mortality = 0"))

       ### multiple comparison procedures
       ### set up a one-way ANOVA
       amod <- aov(breaks ~ tension, data = warpbreaks)

       ### set up all-pair comparisons for factor `tension'
       ### using a symbolic description (`type' argument 
       ### to `contrMat()')
       glht(amod, linfct = mcp(tension = "Tukey"))

       ### alternatively, describe differences symbolically
       glht(amod, linfct = mcp(tension = c("M - L = 0", 
                                           "H - L = 0",
                                           "H - M = 0")))

       ### alternatively, define contrast matrix directly
       contr <- rbind("M - L" = c(-1, 1, 0),
                      "H - L" = c(-1, 0, 1), 
                      "H - M" = c(0, -1, 1))
       glht(amod, linfct = mcp(tension = contr))

       ### alternatively, define linear function for coef(amod)
       ### instead of contrasts for `tension'
       ### (take model contrasts and intercept into account)
       glht(amod, linfct = cbind(0, contr %*% contr.treatment(3)))

