% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/estimability.R
\docType{data}
\name{nonest.basis}
\alias{nonest.basis}
\alias{nonest.basis.default}
\alias{nonest.basis.qr}
\alias{nonest.basis.matrix}
\alias{nonest.basis.lm}
\alias{nonest.basis.svd}
\alias{legacy.nonest.basis}
\alias{is.estble}
\alias{all.estble}
\title{Estimability Tools}
\usage{
nonest.basis(x, ...)

\method{nonest.basis}{default}(x, ...)

\method{nonest.basis}{qr}(x, ...)

\method{nonest.basis}{matrix}(
  x,
  tol = 5e-08,
  rank = attr(x, "rank"),
  pivot = attr(x, "pivot"),
  ...
)

\method{nonest.basis}{lm}(x, ...)

\method{nonest.basis}{svd}(x, tol = 5e-08, rank = NULL, pivot = NULL, ...)

legacy.nonest.basis(x, ...)

is.estble(x, nbasis, tol = 1e-08)

all.estble
}
\arguments{
\item{x}{For \code{nonest.basis}, an object of a class in
\samp{methods("nonest.basis")}. Or, in \code{is.estble}, a numeric vector
or matrix for assessing estimability of \samp{sum(x * beta)}, where
\code{beta} is the vector of regression coefficients.}

\item{...}{Additional arguments passed to other methods.}

\item{tol}{Numeric tolerance for assessing rank or nonestimability. For
determining rank, singular values less than \code{tol} times the largest
singular value are regarded as zero. For determining estimability with a
nonzero \eqn{x}, \eqn{\beta'x} is assessed by whether or not \eqn{||N'x||^2
< \tau ||x'x||^2}, where \eqn{N} and \eqn{\tau} denote \code{nbasis} and
\code{tol}, respectively.}

\item{rank}{Optional integer value. If not \code{NULL}, it is used in place
of \code{tol} to decide the rank of the model matrix}

\item{pivot}{Optional integer vector of length equal to the number of columns
in the model matrix. If non-\code{NULL}, it is assumed that this specifies
the order of columns in \code{x} relative to the order of predictors in the
model matrix, and the returned non-estimable basis is permuted accordingly.}

\item{nbasis}{Matrix whose columns span the null space of the model matrix.
Such a matrix is returned by \code{nonest.basis}.}
}
\value{
When \eqn{X} is not full-rank, the methods for \code{nonest.basis}
  return a basis for the null space of \eqn{X}. The number of rows is equal
  to the number of regression coefficients (\emph{including} any \code{NA}s);
  and the number of columns is equal to the rank deficiency of the model
  matrix. The columns are orthonormal. If the model is full-rank, then
  \code{nonest.basis} returns \code{all.estble}. The \code{matrix} method
  uses \eqn{X} itself, the \code{qr} method uses the \eqn{QR} decomposition
  of \eqn{X}, and the \code{lm} method recovers the required information from
  the object.

  The function \code{is.estble} returns a logical value (or vector, if
  \code{x} is a matrix) that is \code{TRUE} if the function is estimable and
  \code{FALSE} if not.
}
\description{
This documents the functions needed to test estimability of linear functions 
of regression coefficients.
}
\details{
Consider a linear model \eqn{y = X\beta + E}. If \eqn{X} is not of full rank,
it is not possible to estimate \eqn{\beta} uniquely. However, \eqn{X\beta}
\emph{is} uniquely estimable, and so is \eqn{a'X\beta} for any conformable
vector \eqn{a}. Since \eqn{a'X} comprises a linear combination of the rows of
\eqn{X}, it follows that we can estimate any linear function where the
coefficients lie in the row space of \eqn{X}. Equivalently, we can check to
ensure that the coefficients are orthogonal to the null space of \eqn{X}.
Because estimability constraints are entirely determined by \eqn{X}, these 
methods apply to a rich class of models that includes linear models, generalized
linear models, mixed models, and models with more general correlated-error
structures (e.g., spatial models, time series models).

The \code{nonest.basis} method for class \code{'svd'} is not really
functional as a method because there is no \code{"svd"} class (at least in R
<= 4.2.0). But the function \code{nonest.basis.svd} is exported and may be
called directly; it works with results of \code{\link{svd}} or
\code{\link{La.svd}}. We \emph{require} \code{x$v} to be the complete matrix
of right singular values; but we do not need \code{x$u} at all.

The \code{default} method does serve as an \code{svd} method, in that it only
works if \code{x} has the required elements of an SVD result, in which case
it passes it to \code{nonest.basis.svd}.

The \code{matrix} method runs \code{nonest.basis.svd(svd(x, nu = 0))}. The
\code{lm} method runs the \code{qr} method on \code{x$qr}.

The function \code{legacy.nonest.basis} is the original default method in
early versions of the \pkg{estimability} package. It may be called with
\code{x} being either a matrix or a \code{qr} object, and after obtaining the
\code{R} matrix, it uses an additional QR decomposition of \code{t(R)} to
obtain the needed basis. (The current \code{nonest.basis} method for
\code{qr} objects is instead based on the singular-value decomposition of R,
and requires much simpler code.)

The constant \code{all.estble} is simply a 1 x 1 matrix of \code{NA}. This
specifies a trivial non-estimability basis, and using it as \code{nbasis}
will cause everything to test as estimable.
}
\section{Use with Cholesky decompositions}{
 If the \code{\link{chol}} function
  is called with \code{pivot = TRUE}, the returned matrix is suitable to
  provide to the \code{matrix} method of \code{nonest.basis}, and the
  returned basis is correctly pivoted without specifying \code{pivot}
  explicitly.

  This works because the Cholesky decomposition \eqn{R} of \eqn{X'X} (as constructed by
  \code{chol()}) satisfies \eqn{X'X = R'R}, implying that the rows of
  \eqn{X'X} are linear combinations of the rows of \eqn{R}; and they are both
  of equal rank - so \eqn{R} and \eqn{X'X} have the same row space.
}

\examples{
require(estimability)

X <- cbind(rep(1,5), 1:5, 5:1, 2:6)
( nb <- nonest.basis(X) )

# via the singular-value decomposition
SVD <- svd(X, nu = 0)    # we don't need the U part of UDV'
nonest.basis.svd(SVD)    # same result as above

# Via the Cholesky decomposition of X'X
ch <- chol(t(X) \%*\% X, pivot = TRUE) |> suppressWarnings()
( nb.chol <- nonest.basis(ch) )

# Test estimability of some linear functions for this X matrix
lfs <- rbind(c(1,4,2,5), c(2,3,9,5), c(1,2,2,1), c(0,1,-1,1))
is.estble(lfs, nb)
is.estble(lfs, nb.chol) # same results even though nb.chol is not identical to nb

# Illustration on 'lm' objects:
warp.lm1 <- lm(breaks ~ wool * tension, data = warpbreaks,
    subset = -(26:38),
    contrasts = list(wool = "contr.treatment", tension = "contr.treatment"))
zapsmall(warp.nb1 <- nonest.basis(warp.lm1))

# different parameterization of the same model:
warp.lm2 <- update(warp.lm1,
    contrasts = list(wool = "contr.sum", tension = "contr.helmert"))
zapsmall(warp.nb2 <- nonest.basis(warp.lm2))

# These bases depend of the parameterizations, but they both 
# correctly identify the empty cell
wcells = with(warpbreaks, expand.grid(wool = levels(wool), tension = levels(tension)))
epredict(warp.lm1, newdata = wcells, nbasis = warp.nb1)
epredict(warp.lm2, newdata = wcells, nbasis = warp.nb2)

}
\keyword{datasets}
