R: Sparse Vector Classes

sparseVector-class {Matrix} | R Documentation

## Sparse Vector Classes

### Description

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.

  Note that `"nsparseVector"`s have no `x` slot. Further, mainly for ease of method definitions, we've defined the class union (see `setClassUnion`) of all sparse vector classes which have an `x` slot, as class `"xsparseVector"`.

### 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.

### See Also

`sparseVector()` for friendly construction of sparse vectors (apart from `as(*, "sparseVector")`).

### Examples

    getClass("sparseVector")
    getClass("dsparseVector")
    getClass("xsparseVector")# those with an 'x' slot

    sx <- c(0,0,3, 3.2, 0,0,0,-3:1,0,0,2,0,0,5,0,0)
    (ss <- as(sx, "sparseVector"))

    ix <- as.integer(round(sx))
    (is <- as(ix, "sparseVector")) ## an "isparseVector" (!)
    (ns <- sparseVector(i= c(7, 3, 2), length = 10)) # "nsparseVector"
    ## rep() works too:
    (ri <- rep(is, length.out= 25))

    ## Using `dim<-`  as in base R :
    r <- ss
    dim(r) <- c(4,5) # becomes a sparse Matrix:
    r
    ## or coercion (as as.matrix() in base R):
    as(ss, "Matrix")
    stopifnot(all(ss == print(as(ss, "CsparseMatrix"))))

    ## currently has "non-structural" FALSE -- printing as ":"
    (lis <- is & FALSE)
    (nn <- is[is == 0]) # all "structural" FALSE

    ## NA-case
    sN <- sx; sN[4] <- NA
    (svN <- as(sN, "sparseVector"))

    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)

    system.time(for(i in 1:4) hv <- head(v, 1e6))
    ##   user  system elapsed
    ##  0.033   0.000   0.032
    system.time(for(i in 1:4) h2 <- v[1:1e6])
    ##   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))
    (T20 <- toeplitz(x20))
    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))
    (c2 <- c(ns, is, FALSE))
    (c3 <- c(ns, !ns, TRUE, NA, FALSE))
    (c4 <- c(ns, rev(ns)))
    ## here, c() would produce a list {not dispatching to c.sparseVector()}
    (c5 <- c.sparseVector(0,0, x20))

    ## checking (consistency)
    .v <- as.vector
    .s <- function(v) as(v, "sparseVector")
    stopifnot(
      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),
      all.equal(c5, .s(c(0,0, .v(x20))),                     tol=0)
    )

[Package Matrix version 1.3-4 Index]