R: Permutation matrices

pMatrix-class {Matrix} | R Documentation

## Permutation matrices

### Description

The `"pMatrix"` class is the class of permutation matrices, stored as 1-based integer permutation vectors.

### Objects from the Class

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

### Slots

`perm`:

  An integer, 1-based permutation vector, i.e. an integer vector of length `Dim[1]` whose elements form a permutation of `1:Dim[1]`.

`Dim`:

  Object of class `"integer"`. The dimensions of the matrix which must be a two-element vector of equal, non-negative integers.

`Dimnames`:

  list of length two; each component containing NULL or a `character` vector length equal the corresponding `Dim` element.

### Extends

Class `"sparseMatrix"` and `"generalMatrix"`, directly.

### Methods

%*%

  `signature(x = "matrix", y = "pMatrix")` and other signatures (use `showMethods("%*%", class="pMatrix")`): ...

coerce

  `signature(from = "integer", to = "pMatrix")`: This is enables typical `"pMatrix"` construction, given a permutation vector of `1:n`, see the first example.

coerce

  `signature(from = "numeric", to = "pMatrix")`: a user convenience, to allow `as(perm, "pMatrix")` for numeric `perm` with integer values.

coerce

  `signature(from = "pMatrix", to = "matrix")`: coercion to a traditional FALSE/TRUE `matrix` of `mode` `logical`. (in earlier version of Matrix, it resulted in a 0/1-integer matrix; `logical` makes slightly more sense, corresponding better to the “natural” sparseMatrix counterpart, `"ngTMatrix"`.)

coerce

  `signature(from = "pMatrix", to = "ngTMatrix")`: coercion to sparse logical matrix of class `ngTMatrix`.

determinant

  `signature(x = "pMatrix", logarithm="logical")`: Since permutation matrices are orthogonal, the determinant must be +1 or -1. In fact, it is exactly the sign of the permutation.

solve

  `signature(a = "pMatrix", b = "missing")`: return the inverse permutation matrix.

t

  `signature(x = "pMatrix")`: return the transpose of the permuation matrix (which is also the inverse of the permutation matrix).

### Note

The inverse of the typical `"pMatrix"` constructor, `P <- as(ip, "pMatrix")` is simply `ip <- P@perm`.

Subsetting (“indexing”, including, `diag`) `"pMatrix"` objects treats themas nonzero-pattern matrices, i.e., as `"ngTMatrix"` such that non-matrix subsetting result in `logical` vectors. Sub-assignment (`M[i,j] <- v`) is not sensible and hence an error for these permutation matrices.

### Examples

    (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!)

[Package Matrix version 1.0-6 Index]