Matrix (version 1.2-8)

indMatrix-class: Index Matrices

Description

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.

Objects from the Class

Objects can be created by calls of the form new("indMatrix", ...) or by coercion from an integer index vector, see below.

Slots

Extends

Class "sparseMatrix" and "generalMatrix", directly.

Methods

Details

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 * 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.

See Also

The permutation matrices pMatrix are special index matrices. The “pattern” matrices, nMatrix and its subclasses.

Examples

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, "ngTMatrix")
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 <- suppressWarnings(rBind(I1, I2)))
stopifnot(is(I12, "indMatrix"),
          if(getRversion() >= "3.2.0") identical(I12, rbind(I1, I2)) else TRUE,
	  colSums(I12) == c(2L,2:4,4:2))