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
_f_o_r _l_m, _g_l_m, _l_m_e, _a_n_d _g_e_e_s_e _o_b_j_e_c_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, and geese objects

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

     estimable(obj, cm, beta0, conf.int=NULL, joint.test=FALSE, show.beta0)
     .wald(obj, cm,beta0=rep(0, ifelse(is.null(nrow(cm)), 1, nrow(cm))))

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

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

      cm: Matrix specifying estimable linear functions or contrasts
          (one per row). The number of columns must match the number of
          fitted coefficients in the model.

   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.

_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 the rows of 'cm'.  The
     estimates and their variances are obtained by applying the matrix
     '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.

     The '.wald' function is called internally by 'estimable' and is
     not intended for direct use.

_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 parameter 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
     Gregory_R_Warnes\@groton.pfizer.com, and Sren Hjsgaard
     sorenh@agrsci.dk

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

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

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

     # simple contrast and confidence interval
     y <- rnorm(100)
     x <-  cut(rnorm(100, mean=y, sd=0.25),c(-4,-1.5,0,1.5,4))
     reg <- lm(y ~ x)
     estimable(reg, c(    0,   1,    0,   -1) )

     # Fit a spline with a single knot at 0.5 and plot the *pointwise*
     # confidence intervals
     library(gplots)
     x2 <- rnorm(100,mean=y,sd=0.5)
     reg2 <- lm(y ~ x + x2 + pmax(x2-0.5,0) )
     range <- seq(-2,2,,50)
     tmp <- estimable(reg2,cbind(1,0,0,1,range,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
     # conficence intervals on a contrast.
     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( lambda1 = c(1,0,1,0,0,0),
                  lambda2 = c(1,0,0,1,0,0))
     estimable(lm1,cm)
     estimable(glm1,cm)

