\HeaderA{pMatrix-class}{Permutation matrices}{pMatrix.Rdash.class}
\aliasA{-,pMatrix,missing-method}{pMatrix-class}{.Rdash.,pMatrix,missing.Rdash.method}
\aliasA{coerce,integer,pMatrix-method}{pMatrix-class}{coerce,integer,pMatrix.Rdash.method}
\aliasA{coerce,matrix,pMatrix-method}{pMatrix-class}{coerce,matrix,pMatrix.Rdash.method}
\aliasA{coerce,nMatrix,pMatrix-method}{pMatrix-class}{coerce,nMatrix,pMatrix.Rdash.method}
\aliasA{coerce,numeric,pMatrix-method}{pMatrix-class}{coerce,numeric,pMatrix.Rdash.method}
\aliasA{coerce,pMatrix,CsparseMatrix-method}{pMatrix-class}{coerce,pMatrix,CsparseMatrix.Rdash.method}
\aliasA{coerce,pMatrix,dMatrix-method}{pMatrix-class}{coerce,pMatrix,dMatrix.Rdash.method}
\aliasA{coerce,pMatrix,dsparseMatrix-method}{pMatrix-class}{coerce,pMatrix,dsparseMatrix.Rdash.method}
\aliasA{coerce,pMatrix,lMatrix-method}{pMatrix-class}{coerce,pMatrix,lMatrix.Rdash.method}
\aliasA{coerce,pMatrix,matrix-method}{pMatrix-class}{coerce,pMatrix,matrix.Rdash.method}
\aliasA{coerce,pMatrix,ngeMatrix-method}{pMatrix-class}{coerce,pMatrix,ngeMatrix.Rdash.method}
\aliasA{coerce,pMatrix,ngTMatrix-method}{pMatrix-class}{coerce,pMatrix,ngTMatrix.Rdash.method}
\aliasA{coerce,pMatrix,nMatrix-method}{pMatrix-class}{coerce,pMatrix,nMatrix.Rdash.method}
\aliasA{coerce,pMatrix,nsparseMatrix-method}{pMatrix-class}{coerce,pMatrix,nsparseMatrix.Rdash.method}
\aliasA{coerce,pMatrix,TsparseMatrix-method}{pMatrix-class}{coerce,pMatrix,TsparseMatrix.Rdash.method}
\aliasA{crossprod,pMatrix,missing-method}{pMatrix-class}{crossprod,pMatrix,missing.Rdash.method}
\aliasA{determinant,pMatrix,logical-method}{pMatrix-class}{determinant,pMatrix,logical.Rdash.method}
\aliasA{is.na,pMatrix-method}{pMatrix-class}{is.na,pMatrix.Rdash.method}
\aliasA{solve,Matrix,pMatrix-method}{pMatrix-class}{solve,Matrix,pMatrix.Rdash.method}
\aliasA{solve,pMatrix,missing-method}{pMatrix-class}{solve,pMatrix,missing.Rdash.method}
\aliasA{Summary,pMatrix-method}{pMatrix-class}{Summary,pMatrix.Rdash.method}
\aliasA{t,pMatrix-method}{pMatrix-class}{t,pMatrix.Rdash.method}
\aliasA{tcrossprod,pMatrix,missing-method}{pMatrix-class}{tcrossprod,pMatrix,missing.Rdash.method}
\aliasA{[<-,pMatrix,index,ANY,ANY-method}{pMatrix-class}{[<.Rdash.,pMatrix,index,ANY,ANY.Rdash.method}
\aliasA{[<-,pMatrix,missing,index,ANY-method}{pMatrix-class}{[<.Rdash.,pMatrix,missing,index,ANY.Rdash.method}
\aliasA{\%*\%,Matrix,pMatrix-method}{pMatrix-class}{.Rpcent.*.Rpcent.,Matrix,pMatrix.Rdash.method}
\aliasA{\%*\%,matrix,pMatrix-method}{pMatrix-class}{.Rpcent.*.Rpcent.,matrix,pMatrix.Rdash.method}
\aliasA{\%*\%,pMatrix,Matrix-method}{pMatrix-class}{.Rpcent.*.Rpcent.,pMatrix,Matrix.Rdash.method}
\aliasA{\%*\%,pMatrix,matrix-method}{pMatrix-class}{.Rpcent.*.Rpcent.,pMatrix,matrix.Rdash.method}
\aliasA{\%*\%,pMatrix,pMatrix-method}{pMatrix-class}{.Rpcent.*.Rpcent.,pMatrix,pMatrix.Rdash.method}
\keyword{classes}{pMatrix-class}
\begin{Description}\relax
The \code{"pMatrix"} class is the class of permutation
matrices, stored as 1-based integer permutation vectors.
\end{Description}
\begin{Section}{Objects from the Class}
Objects can be created by calls of the form \code{new("pMatrix", ...)}
or by coercion from an integer permutation vector, see below.
\end{Section}
\begin{Section}{Slots}
\describe{
\item[\code{perm}:] An integer, 1-based permutation vector, i.e.
an integer vector of length \code{Dim[1]} whose elements form a
permutation of \code{1:Dim[1]}.
\item[\code{Dim}:] Object of class \code{"integer"}. The dimensions
of the matrix which must be a two-element vector of equal,
non-negative integers.
\item[\code{Dimnames}:] list of length two; each component
containing NULL or a \code{\LinkA{character}{character}} vector length
equal the corresponding \code{Dim} element.
}
\end{Section}
\begin{Section}{Extends}
Class \code{"\LinkA{sparseMatrix}{sparseMatrix.Rdash.class}"} and
\code{"\LinkA{generalMatrix}{generalMatrix.Rdash.class}"}, directly.
\end{Section}
\begin{Section}{Methods}
\describe{
\item[\%*\%] \code{signature(x = "matrix", y = "pMatrix")} and other
signatures (use \code{showMethods("\%*\%", class="pMatrix")}): ... 
\item[coerce] \code{signature(from = "integer", to = "pMatrix")}:
This is enables typical \code{"pMatrix"} construction, given
a permutation vector of \code{1:n}, see the first example.
\item[coerce] \code{signature(from = "numeric", to = "pMatrix")}:
a user convenience, to allow \code{as(perm, "pMatrix")} for
numeric \code{perm} with integer values.
\item[coerce] \code{signature(from = "pMatrix", to = "matrix")}:
coercion to a traditional FALSE/TRUE \code{\LinkA{matrix}{matrix}} of
\code{\LinkA{mode}{mode}} \code{logical}.
(in earlier version of \pkg{Matrix}, it resulted in a 0/1-integer
matrix; \code{logical} makes slightly more sense, corresponding
better to the \dQuote{natural} sparseMatrix counterpart,
\code{"ngTMatrix"}.)

\item[coerce] \code{signature(from = "pMatrix", to = "ngTMatrix")}:
coercion to sparse logical matrix of class \code{\LinkA{ngTMatrix}{ngTMatrix.Rdash.class}}.
\item[determinant] \code{signature(x = "pMatrix", logarithm="logical")}:
Since permutation matrices are orthogonal, the determinant must be
+1 or -1.  In fact, it is exactly the \emph{sign of the
permutation}.
\item[solve] \code{signature(a = "pMatrix", b = "missing")}: return
the inverse permutation matrix.
\item[t] \code{signature(x = "pMatrix")}: return the transpose of
the permuation matrix (which is also the inverse of the
permutation matrix).
}
\end{Section}
\begin{Note}\relax
The inverse of the typical \code{"pMatrix"} constructor,
\code{P <- as(ip, "pMatrix")} is simply \code{ip <- P@perm}.

Subsetting (\dQuote{indexing}, including, \code{\LinkA{diag}{diag}})
\code{"pMatrix"} objects treats themas nonzero-pattern matrices, i.e.,
as \code{"\LinkA{ngTMatrix}{ngTMatrix.Rdash.class}"} such that non-matrix subsetting
result in \code{\LinkA{logical}{logical}} vectors.
Sub-assignment (\code{M[i,j] <- v}) is not sensible and hence an error
for these permutation matrices.
\end{Note}
\begin{Examples}
\begin{ExampleCode}
(pm1 <- as(as.integer(c(2,3,1)), "pMatrix"))
t(pm1) # is the same as
solve(pm1)
pm1 %*% t(pm1) # check that the transpose is the inverse
stopifnot(all(diag(3) == as(pm1 %*% t(pm1), "matrix")),
          is.logical(as(pm1, "matrix")))

set.seed(11)
## random permutation matrix :
(p10 <- as(sample(10),"pMatrix"))

## Permute rows / columns of a numeric matrix :
(mm <- round(array(rnorm(3 * 3), c(3, 3)), 2))
mm %*% pm1
pm1 %*% mm
try(as(as.integer(c(3,3,1)), "pMatrix"))# Error: not a permutation

as(pm1, "ngTMatrix")
p10[1:7, 1:4] # gives an "ngTMatrix" (most economic!)
\end{ExampleCode}
\end{Examples}

