indMatrix-class {Matrix} | R Documentation |

The `"indMatrix"`

class is the class of index
matrices, stored as 1-based integer index vectors. An index matrix is
a matrix with exactly one non-zero entry per row.
Index matrices are useful for mapping observations to unique covariate
values, for example.

Matrix (vector) multiplication with index matrices is equivalent to replicating and permuting rows, or “sampling rows with replacement”, and is implemented that way in the Matrix package, see the ‘Details’ below.

Matrix (vector) multiplication with index matrices from the left is
equivalent to replicating and permuting rows of the matrix on the right
hand side. (Similarly, matrix multiplication with the transpose of an
index matrix from the right corresponds to selecting *columns*.)
The crossproduct of an index matrix `M`

with itself is a diagonal
matrix with the number of entries in each column of `M`

on the
diagonal, i.e., `M'M=`

`Diagonal(x=table(M@perm))`

.

Permutation matrices (of class `pMatrix`

) are special
cases of index matrices: They are square, of dimension, say, ```
n
\times n
```

, and their index vectors contain exactly all of `1:n`

.

While “row-indexing” (of more than one row *or* using
`drop=FALSE`

) stays within the `"indMatrix"`

class, all
other subsetting/indexing operations (“column-indexing”,
including, `diag`

) on `"indMatrix"`

objects treats
them as nonzero-pattern matrices (`"ngTMatrix"`

specifically), such that non-matrix subsetting results in
`logical`

vectors.
Sub-assignment (`M[i,j] <- v`

) is not sensible and hence an error
for these matrices.

Objects can be created by calls of the form `new("indMatrix", ...)`

or by coercion from an integer index vector, see below.

`perm`

:An integer, 1-based index vector, i.e. an integer vector of length

`Dim[1]`

whose elements are taken from`1:Dim[2]`

.`Dim`

:`integer`

vector of length two. In some applications, the matrix will be skinny, i.e., with at least as many rows as columns.`Dimnames`

:a

`list`

of length two where each component is either`NULL`

or a`character`

vector of length equal to the corresponding`Dim`

element.

Class `"sparseMatrix"`

and
`"generalMatrix"`

, directly.

- %*%
`signature(x = "matrix", y = "indMatrix")`

and other signatures (use`showMethods("%*%", class="indMatrix")`

): ...- coerce
`signature(from = "integer", to = "indMatrix")`

: This enables typical`"indMatrix"`

construction, given an index vector from elements in`1:Dim[2]`

, see the first example.- coerce
`signature(from = "numeric", to = "indMatrix")`

: a user convenience, to allow`as(perm, "indMatrix")`

for numeric`perm`

with integer values.- coerce
`signature(from = "list", to = "indMatrix")`

: The list must have two (integer-valued) entries: the first giving the index vector with elements in`1:Dim[2]`

, the second giving`Dim[2]`

. This allows`"indMatrix"`

construction for cases in which the values represented by the rightmost column(s) are not associated with any observations, i.e., in which the index does not contain values`Dim[2], Dim[2]-1, Dim[2]-2, ...`

- coerce
`signature(from = "indMatrix", to = "matrix")`

: coercion to a traditional FALSE/TRUE`matrix`

of`mode`

`logical`

.- coerce
`signature(from = "indMatrix", to = "ngTMatrix")`

: coercion to sparse logical matrix of class`ngTMatrix`

.- t
`signature(x = "indMatrix")`

: return the transpose of the index matrix (which is no longer an`indMatrix`

, but of class`ngTMatrix`

.- colSums, colMeans, rowSums, rowMeans
`signature(x = "indMatrix")`

: return the column or row sums or means.- rbind2
`signature(x = "indMatrix", y = "indMatrix")`

: a fast method for rowwise catenation of two index matrices (with the same number of columns).- kronecker
`signature(X = "indMatrix", Y = "indMatrix")`

: return the kronecker product of two index matrices, which corresponds to the index matrix of the interaction of the two.

Fabian Scheipl, Uni Muenchen, building on existing
`"pMatrix"`

, after a nice hike's conversation with
Martin Maechler; diverse tweaks by the latter.
The `crossprod(x,y)`

and `kronecker(x,y)`

methods when both arguments are `"indMatrix"`

have been made
considerably faster thanks to a suggestion by Boris Vaillant.

The permutation matrices `pMatrix`

are special
index matrices. The “pattern” matrices,
`nMatrix`

and its subclasses.

```
p1 <- as(c(2,3,1), "pMatrix")
(sm1 <- as(rep(c(2,3,1), e=3), "indMatrix"))
stopifnot(all(sm1 == p1[rep(1:3, each=3),]))
## row-indexing of a <pMatrix> turns it into an <indMatrix>:
class(p1[rep(1:3, each=3),])
set.seed(12) # so we know '10' is in sample
## random index matrix for 30 observations and 10 unique values:
(s10 <- as(sample(10, 30, replace=TRUE),"indMatrix"))
## Sample rows of a numeric matrix :
(mm <- matrix(1:10, nrow=10, ncol=3))
s10 %*% mm
set.seed(27)
IM1 <- as(sample(1:20, 100, replace=TRUE), "indMatrix")
IM2 <- as(sample(1:18, 100, replace=TRUE), "indMatrix")
(c12 <- crossprod(IM1,IM2))
## same as cross-tabulation of the two index vectors:
stopifnot(all(c12 - unclass(table(IM1@perm, IM2@perm)) == 0))
# 3 observations, 4 implied values, first does not occur in sample:
as(2:4, "indMatrix")
# 3 observations, 5 values, first and last do not occur in sample:
as(list(2:4, 5), "indMatrix")
as(sm1, "nMatrix")
s10[1:7, 1:4] # gives an "ngTMatrix" (most economic!)
s10[1:4, ] # preserves "indMatrix"-class
I1 <- as(c(5:1,6:4,7:3), "indMatrix")
I2 <- as(7:1, "pMatrix")
(I12 <- rbind(I1, I2))
stopifnot(is(I12, "indMatrix"),
identical(I12, rbind(I1, I2)),
colSums(I12) == c(2L,2:4,4:2))
```

[Package *Matrix* version 1.5-1 Index]