Sparse Vector Classes

Sparse Vector Classes: The virtual mother class "sparseVector" has the five actual daughter classes "dsparseVector", "isparseVector", "lsparseVector", "nsparseVector", and "zsparseVector", where we've mainly implemented methods for the d*, l* and n* ones.

Slots

length:

class "numeric" - the length of the sparse vector. Note that "numeric" can be considerably larger than the maximal "integer", .Machine$integer.max, on purpose.

i:

class "numeric" - the (1-based) indices of the non-zero entries. Must not be NA and strictly sorted increasingly.

Note that "integer" is “part of” "numeric", and can (and often will) be used for non-huge sparseVectors.

x:

(for all but "nsparseVector"): the non-zero entries. This is of class "numeric" for class "dsparseVector", "logical" for class "lsparseVector", etc.

Methods

length

signature(x = "sparseVector"): simply extracts the length slot.

show

signature(object = "sparseVector"): The show method for sparse vectors prints “structural” zeroes as "." using the non-exported prSpVector function which allows further customization such as replacing "." by " " (blank).

Note that options(max.print) will influence how many entries of large sparse vectors are printed at all.

as.vector

signature(x = "sparseVector", mode = "character") coerces sparse vectors to “regular”, i.e., atomic vectors. This is the same as as(x, "vector").

as

..: see coerce below

coerce

signature(from = "sparseVector", to = "sparseMatrix"), and

coerce

signature(from = "sparseMatrix", to = "sparseVector"), etc: coercions to and from sparse matrices (sparseMatrix) are provided and work analogously as in standard R, i.e., a vector is coerced to a 1-column matrix.

dim<-

signature(x = "sparseVector", value = "integer") coerces a sparse vector to a sparse Matrix, i.e., an object inheriting from sparseMatrix, of the appropriate dimension.

head

signature(x = "sparseVector"): as with R's (package util) head, head(x,n) (for $n >= 1$) is equivalent to x[1:n], but here can be much more efficient, see the example.

tail

signature(x = "sparseVector"): analogous to head, see above.

toeplitz

signature(x = "sparseVector"): as toeplitz(x), produce the $n \times n$ Toeplitz matrix from x, where n = length(x).

rep

signature(x = "sparseVector") repeat x, with the same argument list (x, times, length.out, each, ...) as the default method for rep().

which

signature(x = "nsparseVector") and

which

signature(x = "lsparseVector") return the indices of the non-zero entries (which is trivial for sparse vectors).

Ops

signature(e1 = "sparseVector", e2 = "*"): define arithmetic, compare and logic operations, (see Ops).

Summary

signature(x = "sparseVector"): define all the Summary methods.

[

signature(x = "atomicVector", i = ...): not only can you subset (aka “index into”) sparseVectors x[i] using sparseVectors i, but we also support efficient subsetting of traditional vectors x by logical sparse vectors (i.e., i of class "nsparseVector" or "lsparseVector").

is.na, is.finite, is.infinite

(x = "sparseVector"), and

is.na, is.finite, is.infinite

(x = "nsparseVector"): return logical or "nsparseVector" of the same length as x, indicating if/where x is NA (or NaN), finite or infinite, entirely analogously to the corresponding base R functions.

c.sparseVector() is an S3 method for all "sparseVector"s, but automatic dispatch only happens for the first argument, so it is useful also as regular R function, see the examples.

Examples

getClass("sparseVector")
#> Virtual Class "sparseVector" [package "Matrix"]
#> 
#> Slots:
#>                       
#> Name:   length       i
#> Class: numeric numeric
#> 
#> Extends: "replValueSp"
#> 
#> Known Subclasses: "nsparseVector", "lsparseVector", "isparseVector", "dsparseVector", 
#> "zsparseVector"
getClass("dsparseVector")
#> Class "dsparseVector" [package "Matrix"]
#> 
#> Slots:
#>                               
#> Name:        x  length       i
#> Class: numeric numeric numeric
#> 
#> Extends: 
#> Class "sparseVector", directly
#> Class "replValueSp", by class "sparseVector", distance 2

sx <- c(0,0,3, 3.2, 0,0,0,-3:1,0,0,2,0,0,5,0,0)
(ss <- as(sx, "sparseVector"))
#> sparse vector (nnz/length = 8/20) of class "dsparseVector"
#>  [1]    .    .  3.0  3.2    .    .    . -3.0 -2.0 -1.0    .  1.0    .    .  2.0
#> [16]    .    .  5.0    .    .

ix <- as.integer(round(sx))
(is <- as(ix, "sparseVector")) ## an "isparseVector" (!)
#> sparse vector (nnz/length = 8/20) of class "isparseVector"
#>  [1]  .  .  3  3  .  .  . -3 -2 -1  .  1  .  .  2  .  .  5  .  .
(ns <- sparseVector(i= c(7, 3, 2), length = 10)) # "nsparseVector"
#> sparse vector (nnz/length = 3/10) of class "nsparseVector"
#>  [1] . | | . . . | . . .
## rep() works too:
(ri <- rep(is, length.out= 25))
#> sparse vector (nnz/length = 10/25) of class "isparseVector"
#>  [1]  .  .  3  3  .  .  . -3 -2 -1  .  1  .  .  2  .  .  5  .  .  .  .  3  3  .

## Using `dim<-`  as in base R :
r <- ss
dim(r) <- c(4,5) # becomes a sparse Matrix:
r
#> 4 x 5 sparse Matrix of class "dgTMatrix"
#>                   
#> [1,] .    . -2 . .
#> [2,] .    . -1 . 5
#> [3,] 3.0  .  . 2 .
#> [4,] 3.2 -3  1 . .
## or coercion (as as.matrix() in base R):
as(ss, "Matrix")
#> 20 x 1 sparse Matrix of class "dgCMatrix"
#>           
#>  [1,]  .  
#>  [2,]  .  
#>  [3,]  3.0
#>  [4,]  3.2
#>  [5,]  .  
#>  [6,]  .  
#>  [7,]  .  
#>  [8,] -3.0
#>  [9,] -2.0
#> [10,] -1.0
#> [11,]  .  
#> [12,]  1.0
#> [13,]  .  
#> [14,]  .  
#> [15,]  2.0
#> [16,]  .  
#> [17,]  .  
#> [18,]  5.0
#> [19,]  .  
#> [20,]  .  
stopifnot(all(ss == print(as(ss, "CsparseMatrix"))))
#> 20 x 1 sparse Matrix of class "dgCMatrix"
#>           
#>  [1,]  .  
#>  [2,]  .  
#>  [3,]  3.0
#>  [4,]  3.2
#>  [5,]  .  
#>  [6,]  .  
#>  [7,]  .  
#>  [8,] -3.0
#>  [9,] -2.0
#> [10,] -1.0
#> [11,]  .  
#> [12,]  1.0
#> [13,]  .  
#> [14,]  .  
#> [15,]  2.0
#> [16,]  .  
#> [17,]  .  
#> [18,]  5.0
#> [19,]  .  
#> [20,]  .  

## currently has "non-structural" FALSE -- printing as ":"
(lis <- is & FALSE)
#> sparse vector (nnz/length = 0/20) of class "lsparseVector"
#>  [1] . . . . . . . . . . . . . . . . . . . .
(nn <- is[is == 0]) # all "structural" FALSE
#> sparse vector (nnz/length = 0/12) of class "isparseVector"
#>  [1] . . . . . . . . . . . .

## NA-case
sN <- sx; sN[4] <- NA
(svN <- as(sN, "sparseVector"))
#> sparse vector (nnz/length = 8/20) of class "dsparseVector"
#>  [1]  .  .  3 NA  .  .  . -3 -2 -1  .  1  .  .  2  .  .  5  .  .

v <- as(c(0,0,3, 3.2, rep(0,9),-3,0,-1, rep(0,20),5,0),
         "sparseVector")
v <- rep(rep(v, 50), 5000)
set.seed(1); v[sample(v@i, 1e6)] <- 0
str(v)
#> Formal class 'dsparseVector' [package "Matrix"] with 3 slots
#>   ..@ x     : num [1:250000] -3 -1 3 -3 3.2 -3 -1 -1 3.2 -1 ...
#>   ..@ length: int 9500000
#>   ..@ i     : int [1:250000] 14 16 79 90 156 204 206 244 308 320 ...




system.time(for(i in 1:4) hv <- head(v, 1e6))
#>    user  system elapsed 
#>   0.013   0.000   0.014 
##   user  system elapsed
##  0.033   0.000   0.032
system.time(for(i in 1:4) h2 <- v[1:1e6])
#>    user  system elapsed 
#>   0.130   0.016   0.146 
##   user  system elapsed
##  1.317   0.000   1.319

stopifnot(identical(hv, h2),
          identical(is | FALSE, is != 0),
          validObject(svN), validObject(lis), as.logical(is.na(svN[4])),
          identical(is^2 > 0, is & TRUE),
          all(!lis), !any(lis), length(nn@i) == 0, !any(nn), all(!nn),
          sum(lis) == 0, !prod(lis), range(lis) == c(0,0))

## create and use the t(.) method:
t(x20 <- sparseVector(c(9,3:1), i=c(1:2,4,7), length=20))
#> 1 x 20 sparse Matrix of class "dgRMatrix"
#>                                             
#> [1,] 9 3 . 2 . . 1 . . . . . . . . . . . . .
(T20 <- toeplitz(x20))
#> 20 x 20 sparse Matrix of class "dsCMatrix"
#>                                              
#>  [1,] 9 3 . 2 . . 1 . . . . . . . . . . . . .
#>  [2,] 3 9 3 . 2 . . 1 . . . . . . . . . . . .
#>  [3,] . 3 9 3 . 2 . . 1 . . . . . . . . . . .
#>  [4,] 2 . 3 9 3 . 2 . . 1 . . . . . . . . . .
#>  [5,] . 2 . 3 9 3 . 2 . . 1 . . . . . . . . .
#>  [6,] . . 2 . 3 9 3 . 2 . . 1 . . . . . . . .
#>  [7,] 1 . . 2 . 3 9 3 . 2 . . 1 . . . . . . .
#>  [8,] . 1 . . 2 . 3 9 3 . 2 . . 1 . . . . . .
#>  [9,] . . 1 . . 2 . 3 9 3 . 2 . . 1 . . . . .
#> [10,] . . . 1 . . 2 . 3 9 3 . 2 . . 1 . . . .
#> [11,] . . . . 1 . . 2 . 3 9 3 . 2 . . 1 . . .
#> [12,] . . . . . 1 . . 2 . 3 9 3 . 2 . . 1 . .
#> [13,] . . . . . . 1 . . 2 . 3 9 3 . 2 . . 1 .
#> [14,] . . . . . . . 1 . . 2 . 3 9 3 . 2 . . 1
#> [15,] . . . . . . . . 1 . . 2 . 3 9 3 . 2 . .
#> [16,] . . . . . . . . . 1 . . 2 . 3 9 3 . 2 .
#> [17,] . . . . . . . . . . 1 . . 2 . 3 9 3 . 2
#> [18,] . . . . . . . . . . . 1 . . 2 . 3 9 3 .
#> [19,] . . . . . . . . . . . . 1 . . 2 . 3 9 3
#> [20,] . . . . . . . . . . . . . 1 . . 2 . 3 9
stopifnot(is(T20, "symmetricMatrix"), is(T20, "sparseMatrix"),
          identical(unname(as.matrix(T20)),
                    toeplitz(as.vector(x20))))

## c() method for "sparseVector" - also available as regular function
(c1 <- c(x20, 0,0,0, -10*x20))
#> sparse vector (nnz/length = 8/43) of class "dsparseVector"
#>  [1]   9   3   .   2   .   .   1   .   .   .   .   .   .   .   .   .   .   .   .
#> [20]   .   .   .   . -90 -30   . -20   .   . -10   .   .   .   .   .   .   .   .
#> [39]   .   .   .   .   .
(c2 <- c(ns, is, FALSE))
#> sparse vector (nnz/length = 11/31) of class "isparseVector"
#>  [1]  .  1  1  .  .  .  1  .  .  .  .  .  3  3  .  .  . -3 -2 -1  .  1  .  .  2
#> [26]  .  .  5  .  .  .
(c3 <- c(ns, !ns, TRUE, NA, FALSE))
#> sparse vector (nnz/length = 12/23) of class "lsparseVector"
#>  [1]    .    |    |    .    .    .    |    .    .    .    |    .    .    |    |
#> [16]    |    .    |    |    |    | <NA>    .
(c4 <- c(ns, rev(ns)))
#> sparse vector (nnz/length = 6/20) of class "nsparseVector"
#>  [1] . | | . . . | . . . . . . | . . . | | .
## here, c() would produce a list {not dispatching to c.sparseVector()}
(c5 <- c.sparseVector(0,0, x20))
#> sparse vector (nnz/length = 4/22) of class "dsparseVector"
#>  [1] . . 9 3 . 2 . . 1 . . . . . . . . . . . . .

## checking (consistency)
.v <- as.vector
.s <- function(v) as(v, "sparseVector")
stopifnot(exprs = {
    all.equal(c1, .s(c(.v(x20), 0,0,0, -10*.v(x20))),      tol = 0)
    all.equal(c2, .s(c(.v(ns), .v(is), FALSE)),            tol = 0)
    all.equal(c3, .s(c(.v(ns), !.v(ns), TRUE, NA, FALSE)), tol = 0)
    all.equal(c4, .s(c(.v(ns), rev(.v(ns)))),              tol = 0,
              check.class = FALSE)
    all.equal(c5, .s(c(0,0, .v(x20))),                     tol = 0)
})

Slots

Methods

See also

Examples