\HeaderA{mauchly.test}{Mauchly's Test of Sphericity}{mauchly.test}
\methaliasA{mauchly.test.mlm}{mauchly.test}{mauchly.test.mlm}
\methaliasA{mauchly.test.SSD}{mauchly.test}{mauchly.test.SSD}
\keyword{htest}{mauchly.test}
\keyword{models}{mauchly.test}
\keyword{multivariate}{mauchly.test}
\begin{Description}\relax
Tests whether a Wishart-distributed covariance matrix (or
transformation thereof) is proportional to a given matrix.
\end{Description}
\begin{Usage}
\begin{verbatim}
mauchly.test(object, ...)
## S3 method for class 'mlm':
mauchly.test(object,...)
## S3 method for class 'SSD':
mauchly.test(object, Sigma = diag(nrow = p),
   T = Thin.row(proj(M) - proj(X)), M = diag(nrow = p), X = ~0,
   idata = data.frame(index = seq_len(p)), ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{object}] object of class \code{SSD} or \code{mlm}.
\item[\code{Sigma}] matrix to be proportional to.
\item[\code{T}] transformation matrix. By default computed from \code{M} and
\code{X}.
\item[\code{M}] formula or matrix describing the outer projection (see below).
\item[\code{X}] formula or matrix describing the inner projection (see below).
\item[\code{idata}] data frame describing intra-block design.
\item[\code{...}] arguments to be passed to or from other methods.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Mauchly's test test for whether a covariance matrix can be assumed to
be proportional to a given matrix.

This is a generic function with methods for classes \code{"mlm"} and
\code{"\LinkA{SSD}{SSD}"}.

The basic method is for objects of
class \code{SSD} the method for \code{mlm} objects just extracts the
SSD matrix and invokes the corresponding method with the same options
and arguments.   

The \code{T} argument is used to transform the observations prior to
testing. This typically involves transformation to intra-block
differences, but more complicated within-block designs can be
encountered, making more elaborate transformations necessary. A
matrix \code{T} can be given directly or specified as
the difference between two projections onto the spaces spanned by
\code{M} and \code{X}, which in turn can be given as matrices or as
model formulas with respect to \code{idata} (the tests will be
invariant to parametrization of the quotient space \code{M/X}).

The common use of this test is in repeated measurements designs, with
\code{X=\textasciitilde{}1}. This is almost, but not quite the same as testing for
compound symmetry in the untransformed covariance matrix.

Notice that the defaults involve \code{p}, which is calculated
internally as the dimension of the SSD matrix, and a couple of hidden
functions in the \code{stats} namespace, namely \code{proj} which
calculates projection matrices from design matrices or model formulas
and \code{Thin.row} which removes linearly dependent rows from a
matrix until it has full row rank.
\end{Details}
\begin{Value}
An object of class \code{"htest"}
\end{Value}
\begin{Note}\relax
The p-value differs slightly from that of SAS because a second order term
is included in the asymptotic approximation in \R.
\end{Note}
\begin{References}\relax
T. W. Anderson (1958).  \emph{An Introduction to Multivariate
Statistical Analysis.} Wiley.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{SSD}{SSD}}, \code{\LinkA{anova.mlm}{anova.mlm}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
utils::example(SSD) # Brings in the mlmfit and reacttime objects

### traditional test of intrasubj. contrasts
mauchly.test(mlmfit, X=~1) 

### tests using intra-subject 3x2 design
idata <- data.frame(deg=gl(3,1,6, labels=c(0,4,8)),
                    noise=gl(2,3,6, labels=c("A","P")))
mauchly.test(mlmfit, X = ~ deg + noise, idata = idata)
mauchly.test(mlmfit, M = ~ deg + noise, X = ~ noise, idata=idata)
\end{ExampleCode}
\end{Examples}

