\HeaderA{sparse.model.matrix}{Construct Sparse Design / Model Matrices}{sparse.model.matrix}
\keyword{models}{sparse.model.matrix}
\begin{Description}\relax
Construct a Model or \dQuote{Design} Matrix
\end{Description}
\begin{Usage}
\begin{verbatim}
sparse.model.matrix(object, data = environment(object),
                    contrasts.arg = NULL, xlev = NULL, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{object}] an object of an appropriate class.  For the default
method, a model formula or terms object.
\item[\code{data}] a data frame created with \code{\LinkA{model.frame}{model.frame}}.  If
another sort of object, \code{model.frame} is called first.
\item[\code{contrasts.arg}] A list, whose entries are contrasts suitable for
input to the \code{\LinkA{contrasts}{contrasts}} replacement function and
whose names are the names of columns of \code{data} containing
\code{\LinkA{factor}{factor}}s.
\item[\code{xlev}] to be used as argument of \code{\LinkA{model.frame}{model.frame}} if
\code{data} has no \code{"terms"} attribute.
\item[\code{...}] further arguments passed to or from other methods.
\end{ldescription}
\end{Arguments}
\begin{Value}
a sparse matrix, inheriting from \code{\LinkA{CsparseMatrix}{CsparseMatrix.Rdash.class}},
typically of class  \code{\LinkA{dgCMatrix}{dgCMatrix.Rdash.class}}.
\end{Value}
\begin{Author}\relax
Doug Bates and Martin Maechler, with initial suggestions from Tim
Hesterberg.
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{model.matrix}{model.matrix}}, ...
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
dd <- data.frame(a = gl(3,4), b = gl(4,1,12))# balanced 2-way
options("contrasts") # the default:  "contr.treatment"
sparse.model.matrix(~ a + b, dd)
sparse.model.matrix(~ -1+ a + b, dd)# no intercept --> even sparse
sparse.model.matrix(~ a + b, dd, contrasts = list(a="contr.sum"))
sparse.model.matrix(~ a + b, dd, contrasts = list(b="contr.SAS"))

## Sparse method is equivalent to the traditional one :
stopifnot(all(sparse.model.matrix(~ a + b, dd) ==
              Matrix(model.matrix(~ a + b, dd), sparse=TRUE)),
          all(sparse.model.matrix(~ 0+ a + b, dd) ==
              Matrix(model.matrix(~ 0+ a + b, dd), sparse=TRUE)))
\end{ExampleCode}
\end{Examples}

