R: Sparse "pattern" Matrices

nsparseMatrix-classes {Matrix} | R Documentation

## Sparse "pattern" Matrices

### Description

The `nsparseMatrix` class is a virtual class of sparse “pattern” matrices, i.e., binary matrices conceptually with `TRUE`/`FALSE` entries. Only the positions of the elements that are `TRUE` are stored.

These can be stored in the “triplet” form (`TsparseMatrix`, subclasses `ngTMatrix`, `nsTMatrix`, and `ntTMatrix` which really contain pairs, not triplets) or in compressed column-oriented form (class `CsparseMatrix`, subclasses `ngCMatrix`, `nsCMatrix`, and `ntCMatrix`) or–rarely–in compressed row-oriented form (class `RsparseMatrix`, subclasses `ngRMatrix`, `nsRMatrix`, and `ntRMatrix`). The second letter in the name of these non-virtual classes indicates `g`eneral, `s`ymmetric, or `t`riangular.

### Objects from the Class

Objects can be created by calls of the form `new("ngCMatrix", ...)` and so on. More frequently objects are created by coercion of a numeric sparse matrix to the pattern form for use in the symbolic analysis phase of an algorithm involving sparse matrices. Such algorithms often involve two phases: a symbolic phase wherein the positions of the non-zeros in the result are determined and a numeric phase wherein the actual results are calculated. During the symbolic phase only the positions of the non-zero elements in any operands are of interest, hence numeric sparse matrices can be treated as sparse pattern matrices.

### Slots

`uplo`:

  Object of class `"character"`. Must be either "U", for upper triangular, and "L", for lower triangular. Present in the triangular and symmetric classes but not in the general class.

`diag`:

  Object of class `"character"`. Must be either `"U"`, for unit triangular (diagonal is all ones), or `"N"` for non-unit. The implicit diagonal elements are not explicitly stored when `diag` is `"U"`. Present in the triangular classes only.

`p`:

  Object of class `"integer"` of pointers, one for each column (row), to the initial (zero-based) index of elements in the column. Present in compressed column-oriented and compressed row-oriented forms only.

`i`:

  Object of class `"integer"` of length nnzero (number of non-zero elements). These are the row numbers for each TRUE element in the matrix. All other elements are FALSE. Present in triplet and compressed column-oriented forms only.

`j`:

  Object of class `"integer"` of length nnzero (number of non-zero elements). These are the column numbers for each TRUE element in the matrix. All other elements are FALSE. Present in triplet and compressed column-oriented forms only.

`Dim`:

  Object of class `"integer"` - the dimensions of the matrix.

### Methods

coerce

  `signature(from = "dgCMatrix", to = "ngCMatrix")`, and many similar ones; typically you should coerce to `"nsparseMatrix"` (or `"nMatrix"`). Note that coercion to a sparse pattern matrix records all the potential non-zero entries, i.e., explicit (“non-structural”) zeroes are coerced to `TRUE`, not `FALSE`, see the example.

t

  `signature(x = "ngCMatrix")`: returns the transpose of `x`

which

  `signature(x = "lsparseMatrix")`, semantically equivalent to base function `which(x, arr.ind)`; for details, see the `lMatrix` class documentation.

### See Also

the class `dgCMatrix`

### Examples

    (m <- Matrix(c(0,0,2:0), 3,5, dimnames=list(LETTERS[1:3],NULL)))
    ## ``extract the nonzero-pattern of (m) into an nMatrix'':
    nm <- as(m, "nsparseMatrix") ## -> will be a "ngCMatrix"
    str(nm) # no 'x' slot
    nnm <- !nm     # no longer sparse
    (nnm <- as(nnm, "sparseMatrix"))# "lgCMatrix"
    ## consistency check:
    stopifnot(xor(as( nm, "matrix"),
                  as(nnm, "matrix")))

    ## low-level way of adding "non-structural zeros" :
    nnm@x[2:4] <- c(FALSE,NA,NA)
    nnm
    as(nnm, "nMatrix") # NAs *and* non-structural 0  |--->  'TRUE'

    data(KNex)
    nmm <- as(KNex $ mm, "ngCMatrix")
    str(xlx <- crossprod(nmm))# "nsCMatrix"
    stopifnot(isSymmetric(xlx))
    image(xlx, main=paste("crossprod(nmm) : Sparse", class(xlx)))

[Package Matrix version 1.3-4 Index]