\HeaderA{Matrix}{Construct a Classed Matrix}{Matrix}
\keyword{array}{Matrix}
\keyword{algebra}{Matrix}
\begin{Description}\relax
Construct a Matrix of a class that inherits from \code{Matrix}.
\end{Description}
\begin{Usage}
\begin{verbatim}
Matrix(data=NA, nrow=1, ncol=1, byrow=FALSE, dimnames=NULL,
       sparse = NULL, forceCheck = FALSE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{data}] an optional numeric data vector or matrix.
\item[\code{nrow}] when \code{data} is not a matrix, the desired number of rows
\item[\code{ncol}] when \code{data} is not a matrix, the desired number of columns
\item[\code{byrow}] logical.  If \code{FALSE} (the default) the matrix is
filled by columns, otherwise the matrix is filled by rows.
\item[\code{dimnames}] a \code{\LinkA{dimnames}{dimnames}} attribute for the matrix: a
\code{list} of two character components.  They are set if not
\code{\LinkA{NULL}{NULL}} (as per default).
\item[\code{sparse}] logical or \code{NULL}, specifying if the result should
be sparse or not.  By default, it is made sparse when more than half
of the entries are 0.
\item[\code{forceCheck}] logical indicating if the checks for structure
should even happen when \code{data} is already a \code{"Matrix"}
object.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
If either of \code{nrow} or \code{ncol} is not given, an attempt is
made to infer it from the length of \code{data} and the other
parameter.
Further, \code{Matrix()} makes efforts to keep \code{\LinkA{logical}{logical}}
matrices logical, i.e., inheriting from class \code{\LinkA{lMatrix}{lMatrix.Rdash.class}},
and to determine specially structured matrices such as symmetric,
triangular or diagonal ones.  Note that a \emph{symmetric} matrix also
needs symmetric \code{\LinkA{dimnames}{dimnames}}, e.g., by specifying
\code{dimnames = list(NULL,NULL)}, see the examples.

Most of the time, the function works via a traditional (\emph{full})
\code{\LinkA{matrix}{matrix}}.  However, \code{Matrix(0, nrow,ncol)} directly
constructs an \dQuote{empty} \LinkA{sparseMatrix}{sparseMatrix.Rdash.class}, as does
\code{Matrix(FALSE, *)}.

Although it is sometime possible to mix unclassed matrices (created
with \code{matrix}) with ones of class \code{"Matrix"}, it is much
safer to always use carefully constructed ones of class
\code{"Matrix"}.
\end{Details}
\begin{Value}
Returns matrix of a class that inherits from \code{"Matrix"}.
Only if \code{data} is not a \code{\LinkA{matrix}{matrix}} and does not already inherit
from class \code{\LinkA{Matrix}{Matrix.Rdash.class}} are the arguments
\code{nrow}, \code{ncol} and \code{byrow} made use of.
\end{Value}
\begin{SeeAlso}\relax
The classes \code{\LinkA{Matrix}{Matrix.Rdash.class}},
\code{\LinkA{symmetricMatrix}{symmetricMatrix.Rdash.class}},
\code{\LinkA{triangularMatrix}{triangularMatrix.Rdash.class}}, and
\code{\LinkA{diagonalMatrix}{diagonalMatrix.Rdash.class}}; further,
\code{\LinkA{matrix}{matrix}}.

Special matrices can be constructed, e.g., via
\code{\LinkA{sparseMatrix}{sparseMatrix}} (sparse), \code{\LinkA{bdiag}{bdiag}}
(block-diagonal), \code{\LinkA{bandSparse}{bandSparse}} (banded sparse), or
\code{\LinkA{Diagonal}{Diagonal}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
Matrix(0, 3, 2)             # 3 by 2 matrix of zeros -> sparse
Matrix(0, 3, 2, sparse=FALSE)# forced 'dense'
Matrix(1:6, 3, 2)           # a 3 by 2 matrix (+ integer warning)
Matrix(1:6 + 1, nrow=3)

## logical ones:
Matrix(diag(4) >  0)# -> "ldiMatrix" with diag = "U"
Matrix(diag(4) >  0, sparse=TRUE)# -> sparse...
Matrix(diag(4) >= 0)# -> "lsyMatrix" (of all 'TRUE')
## triangular
l3 <- upper.tri(matrix(,3,3))
(M <- Matrix(l3))  # -> "ltCMatrix"
Matrix(! l3)# -> "ltrMatrix"
as(l3, "CsparseMatrix")

Matrix(1:9, nrow=3,
       dimnames = list(c("a", "b", "c"), c("A", "B", "C")))
(I3 <- Matrix(diag(3)))# identity, i.e., unit "diagonalMatrix"
str(I3) # note the empty 'x' slot

(A <- cbind(a=c(2,1), b=1:2))# symmetric *apart* from dimnames
Matrix(A)                    # hence 'dgeMatrix'
(As <- Matrix(A, dimnames = list(NULL,NULL)))# -> symmetric
stopifnot(is(As, "symmetricMatrix"),
          is(Matrix(0, 3,3), "sparseMatrix"),
          is(Matrix(FALSE, 1,1), "sparseMatrix"))
\end{ExampleCode}
\end{Examples}

