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.

rep

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

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"`).

### 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" (!)

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

[Package Matrix version 1.0-6 Index]