W3cubDocs

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

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.

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

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.

Extends

Class "sparseMatrix" and "generalMatrix", directly.

Methods

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

Author(s)

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.

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 <- rbind(I1, I2))
stopifnot(is(I12, "indMatrix"),
          identical(I12, rbind(I1, I2)),
	  colSums(I12) == c(2L,2:4,4:2))

indMatrix-class Index Matrices