% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/estimable.R
\name{estimable}
\alias{estimable}
\alias{estimable.default}
\alias{estimable.mlm}
\title{Contrasts and estimable linear functions of model coefficients}
\usage{
estimable(obj, cm, beta0, conf.int = NULL, show.beta0, ...)

\method{estimable}{default}(obj, cm, beta0, conf.int = NULL, show.beta0, joint.test = FALSE, ...)
}
\arguments{
\item{obj}{Regression (lm, glm, lme, mer, mlm) object.}

\item{cm}{Vector, List, or Matrix specifying estimable linear functions or
contrasts.  See below for details.}

\item{beta0}{Vector of null hypothesis values}

\item{conf.int}{Confidence level.  If provided, confidence intervals will be
computed.}

\item{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.}

\item{...}{ignored}

\item{joint.test}{Logical value. If TRUE a 'joint' Wald test for the
hypothesis \eqn{L \beta=\beta_0} is performed.
Otherwise 'row-wise' tests are performed, i.e. \eqn{(L \beta)[i]=\beta_0[i]}.}
}
\value{
Returns a matrix with one row per linear function.  Columns contain
the beta0 value (optional, see \code{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.
}
\description{
Compute and test contrasts and other estimable linear functions of model
coefficients for for lm, glm, lme, mer, and geese objects
}
\details{
\code{estimable} computes an estimate, test statitic, significance test, and
(optional) confidence interval for each linear functions of the model
coefficients specified by \code{cm}.

The estimable function(s) may be specified via a vector, list, or matrix.
If \code{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 \code{cm} is a list, it
should contain one or more coefficient vectors, which will be used to
construct rows of the contrast matrix.  If \code{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 \code{cm} will be set to zero.

The estimates and their variances are obtained by applying the contrast
matrix (generated from) \code{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, \code{fit.contrast}
may be more convenient.  For computing contrasts between two specific
combinations of model parameters, the \code{contrast} function in Frank
Harrell's 'rms' library (formerly 'Design') may be more convenient.

\%The \code{.wald} function is called internally by \code{estimable} and \%is
not intended for direct use.
}
\note{
The estimated fixed effect parameters of \code{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.
}
\examples{

# 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)

}
\seealso{
\code{\link[=fit.contrast]{fit.contrast()}}, \code{\link[stats:lm]{stats::lm()}},
\code{\link[nlme:lme]{nlme::lme()}}, \code{\link[stats:contrasts]{stats::contrasts()}},
\code{\link[rms:contrast]{rms::contrast()}}
}
\author{
BXC (Bendix Carstensen) \email{b@bxc.dk}, Gregory R. Warnes
\email{greg@warnes.net}, Soren Hojsgaard \email{sorenh@agrsci.dk}, and
Randall C Johnson \email{rjohnson@ncifcrf.gov}
}
\keyword{models}
\keyword{regression}
