# 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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | ```
(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))))
``` |