R: Sparse logical matrices

lsparseMatrix-classes {Matrix} | R Documentation

## Sparse logical matrices

### Description

The `lsparseMatrix` class is a virtual class of sparse matrices with `TRUE`/`FALSE` or `NA` entries. Only the positions of the elements that are `TRUE` are stored.

These can be stored in the “triplet” form (class `TsparseMatrix`, subclasses `lgTMatrix`, `lsTMatrix`, and `ltTMatrix`) or in compressed column-oriented form (class `CsparseMatrix`, subclasses `lgCMatrix`, `lsCMatrix`, and `ltCMatrix`) or–rarely–in compressed row-oriented form (class `RsparseMatrix`, subclasses `lgRMatrix`, `lsRMatrix`, and `ltRMatrix`). The second letter in the name of these non-virtual classes indicates `g`eneral, `s`ymmetric, or `t`riangular.

### Details

Note that triplet stored (`TsparseMatrix`) matrices such as `lgTMatrix` may contain duplicated pairs of indices (i,j) as for the corresponding numeric class `dgTMatrix` where for such pairs, the corresponding `x` slot entries are added. For logical matrices, the `x` entries corresponding to duplicated index pairs (i,j) are “added” as well if the addition is defined as logical or, i.e., “`TRUE + TRUE |-> TRUE`” and “`TRUE + FALSE |-> TRUE`”. Note the use of `uniqTsparse()` for getting an internally unique representation without duplicated (i,j) entries.

### Objects from the Class

Objects can be created by calls of the form `new("lgCMatrix", ...)` and so on. More frequently objects are created by coercion of a numeric sparse matrix to the logical form, e.g. in an expression `x != 0`.

The logical form is also used 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 any numeric sparse matrices can be treated as logical sparse matrices.

### Slots

`x`:

  Object of class `"logical"`, i.e., either `TRUE`, `NA`, or `FALSE`.

`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 row-oriented forms only.

`Dim`:

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

### Methods

coerce

  `signature(from = "dgCMatrix", to = "lgCMatrix")`

t

  `signature(x = "lgCMatrix")`: 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` and `dgTMatrix`

### Examples

    (m <- Matrix(c(0,0,2:0), 3,5, dimnames=list(LETTERS[1:3],NULL)))
    (lm <- (m > 1)) # lgC
    !lm     # no longer sparse
    stopifnot(is(lm,"lsparseMatrix"),
              identical(!lm, m <= 1))

    data(KNex)
    str(mmG.1 <- (KNex $ mm) > 0.1)# "lgC..."
    table(mmG.1@x)# however with many ``non-structural zeros''
    ## from logical to nz_pattern -- okay when there are no NA's :
    nmG.1 <- as(mmG.1, "nMatrix") # <<< has "TRUE" also where mmG.1 had FALSE
    ## from logical to "double"
    dmG.1 <- as(mmG.1, "dMatrix") # has '0' and back:
    lmG.1 <- as(dmG.1, "lMatrix") # has no extra FALSE, i.e. drop0() included
    stopifnot(identical(nmG.1, as((KNex $ mm) != 0,"nMatrix")),
              validObject(lmG.1), all(lmG.1@x),
              # same "logical" but lmG.1 has no 'FALSE' in x slot:
              all(lmG.1 == mmG.1))

    class(xnx <- crossprod(nmG.1))# "nsC.."
    class(xlx <- crossprod(mmG.1))# "dsC.." : numeric
    is0 <- (xlx == 0)
    mean(as.vector(is0))# 99.3% zeros: quite sparse, but
    table(xlx@x == 0)# more than half of the entries are (non-structural!) 0
    stopifnot(isSymmetric(xlx), isSymmetric(xnx),
              ## compare xnx and xlx : have the *same* non-structural 0s :
              sapply(slotNames(xnx),
                     function(n) identical(slot(xnx, n), slot(xlx, n))))

[Package Matrix version 1.3-4 Index]