estimable              package:gmodels              R Documentation

_C_o_n_t_r_a_s_t_s _a_n_d _e_s_t_i_m_a_b_l_e _l_i_n_e_a_r _f_u_n_c_t_i_o_n_s _o_f _m_o_d_e_l _c_o_e_f_f_i_c_i_e_n_t_s

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

     Compute and test contrasts and other estimable linear functions of
     model coefficients for for lm, glm, lme, lmer, and geese objects

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

     estimable(obj, cm, beta0, conf.int=NULL,  show.beta0, ...)
     ## Default S3 method:
     estimable (obj, cm, beta0, conf.int=NULL, show.beta0, joint.test=FALSE, ...)
     ## S3 method for class 'lmer':
     estimable(obj, cm, beta0, conf.int=NULL,
                    show.beta0, sim.lmer=TRUE, n.sim=1000, ...) 
     ## S3 method for class 'mlm':
     estimable(obj, cm, beta0, conf.int=NULL,  show.beta0, ...)

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

     obj: Regression (lm, glm, lme, lmer, mlm) object. 

      cm: Vector, List, or Matrix specifying estimable linear functions
          or contrasts.  See below for details.

   beta0: Vector of null hypothesis values

conf.int: Confidence level.  If provided, confidence intervals will be
          computed.

joint.test: Logical value. If TRUE a 'joint' Wald test for the
          hypothesis L %*% beta=beta0 is performed. Otherwise
          'row-wise' tests are performed, i.e. (L %*% beta)[i]=beta0[i] 

show.beta0: Logical value. If TRUE a column for beta0 will be included
          in the output table.  Defaults to TRUE when beta0 is
          specified, FALSE otherwise.

sim.lmer: Logical value. If TRUE p-values and confidence intervals will
          be estimated using '\Link[Matrix]{mcmcsamp}'. 

   n.sim: Number of MCMC samples to take in '\Link[Matrix]{mcmcsamp}'. 

     ...: ignored

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

     'estimable' computes an estimate, test statitic, significance
     test, and (optional) confidence interval for each linear functions
     of the model coefficients specified by 'cm'.

     The estimable function(s) may be specified via a vector, list, or
     matrix.  If 'cm' is a vector, it should contained named elements
     each of which gives the coefficient to be applied to the
     corresponding parameter. These coefficients will be used to
     construct the contrast matrix, with unspecified model parameters
     assigned zero coefficients. If 'cm' is a list, it should contain
     one or more coefficient vectors, which will be used to construct
     rows of the contrast matrix.  If 'cm' is a matrix, column names
     must match (a subset of) the model parameters, and each row should
     contain the corresponding coefficient to be applied.  Model
     parameters which are not present in the set of column names of
     'cm' will be set to zero.

     The estimates and their variances are obtained by applying the
     contrast matrix (generated from) 'cm' to the model estimates
     variance-covariance matrix.  Degrees of freedom are obtained from
     the appropriate model terms.

     The user is responsible for ensuring that the specified linear
     functions are meaningful.

     For computing contrasts among levels of a single factor,
     'fit.contrast' may be more convenient.  For computing contrasts
     between two specific combinations of model parameters, the
     'contrast' function in Frank Harrell's Design library may be more
     convenient.

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

     Returns a matrix with one row per linear function.  Columns
     contain the beta0 value (optional, see 'show.beta0' above),
     estimated coefficients, standard errors, t values, degrees of
     freedom, two-sided p-values, and the lower and upper endpoints of
     the 1-alpha confidence intervals.

_N_o_t_e:

     The estimated fixed effect parameters of 'lme' objects may have
     different degrees of freedom.  If a specified contrast includes
     nonzero coefficients for parameters with differing degrees of
     freedom, the smallest number of degrees of freedom is used and a
     warning message is issued.

_A_u_t_h_o_r(_s):

     BXC (Bendix Carstensen) bxc\@novonordisk.com,  Gregory R. Warnes
     warnes@bst.rochester.edu, Soren Hojsgaard sorenh@agrsci.dk, and
     Randall C Johnson rjohnson@ncifcrf.gov

_S_e_e _A_l_s_o:

     'fit.contrast', 'lm', 'lme', 'contrasts', 'contrast',

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

     # setup example data
     y <- rnorm(100)
     x <-  cut(rnorm(100, mean=y, sd=0.25),c(-4,-1.5,0,1.5,4))
     levels(x) <- c("A","B","C","D")
     x2 <- rnorm(100, mean=y, sd=0.5)

     # simple contrast and confidence interval
     reg <- lm(y ~ x)
     estimable(reg, c(    0,   1,    0,   -1) )  # full coefficient vector
     estimable(reg, c("xB"=1,"xD"=-1) )          # just the nonzero terms

     # Fit a spline with a single knot at 0.5 and plot the *pointwise*
     # confidence intervals
     library(gplots)
     pm <- pmax(x2-0.5, 0) # knot at 0.5
     reg2 <- lm(y ~ x + x2 + pm )

     range <- seq(-2, 2, , 50)
     tmp <- estimable(reg2,
                      cm=cbind(
                               '(Intercept)'=1,
                               'xC'=1,
                               'x2'=range,
                               'pm'=pmax(range-0.5, 0)
                                ),
                      conf.int=0.95)
     plotCI(x=range, y=tmp[, 1], li=tmp[, 6], ui=tmp[, 7])

     # Fit both linear and quasi-Poisson models to iris data, then compute
     # joint confidence intervals on contrasts for the Species and
     # Sepal.Width by Species interaction terms.
     data(iris)
     lm1  <- lm (Sepal.Length ~ Sepal.Width + Species + Sepal.Width:Species, data=iris)
     glm1 <- glm(Sepal.Length ~ Sepal.Width + Species + Sepal.Width:Species, data=iris, 
                 family=quasipoisson("identity"))

     cm <- rbind(
                 'Setosa vs. Versicolor'   = c(0, 0, 1, 0, 1, 0), 
                 'Setosa vs. Virginica'    = c(0, 0, 0, 1, 0, 1),
                 'Versicolor vs. Virginica'= c(0, 0, 1,-1, 1,-1)
                 )
     estimable(lm1, cm)
     estimable(glm1, cm)

