sparseMatrix: General Sparse Matrix Construction from Nonzero Entries

Description

User friendly construction of a compressed, column-oriented, sparse matrix, inheriting from class '>CsparseMatrix (or '>TsparseMatrix if giveCsparse is false), from locations (and values) of its non-zero entries.

This is the recommended user interface rather than direct new("***Matrix", ....) calls.

Usage

sparseMatrix(i = ep, j = ep, p, x, dims, dimnames,
             symmetric = FALSE, triangular = FALSE, index1 = TRUE,
             repr = "C", giveCsparse = (repr == "C"),
             check = TRUE, use.last.ij = FALSE)

Arguments

i,j

integer vectors of the same length specifying the locations (row and column indices) of the non-zero (or non-TRUE) entries of the matrix. Note that for repeated pairs \((i_k,j_k)\), when x is not missing, the corresponding \(x_k\) are added, in consistency with the definition of the "'>TsparseMatrix" class, unless use.last.ij is true, in which case only the last of the corresponding \((i_k, j_k, x_k)\) triplet is used.

numeric (integer valued) vector of pointers, one for each column (or row), to the initial (zero-based) index of elements in the column (or row). Exactly one of i, j or p must be missing.

optional values of the matrix entries. If specified, must be of the same length as i / j, or of length one where it will be recycled to full length. If missing, the resulting matrix will be a 0/1 pattern matrix, i.e., extending class '>nsparseMatrix.

dims

optional, non-negative, integer, dimensions vector of length 2. Defaults to c(max(i), max(j)).

dimnames

optional list of dimnames; if not specified, none, i.e., NULL ones, are used.

symmetric

logical indicating if the resulting matrix should be symmetric. In that case, only the lower or upper triangle needs to be specified via \((i/j/p)\).

triangular

logical indicating if the resulting matrix should be triangular. In that case, the lower or upper triangle needs to be specified via \((i/j/p)\).

index1

logical scalar. If TRUE, the default, the index vectors i and/or j are 1-based, as is the convention in R. That is, counting of rows and columns starts at 1. If FALSE the index vectors are 0-based so counting of rows and columns starts at 0; this corresponds to the internal representation.

repr

character string, one of "C", "T", or "R", specifying the sparse representation to be used for the result, i.e., one from the super classes '>CsparseMatrix, '>TsparseMatrix, or '>RsparseMatrix.

giveCsparse

(deprecated, replaced with repr): logical indicating if the result should be a '>CsparseMatrix or a '>TsparseMatrix, where the default was TRUE, and now is determined from repr; very often Csparse matrices are more efficient subsequently, but not always.

check

logical indicating if a validity check is performed; do not set to FALSE unless you know what you're doing!

use.last.ij

logical indicating if in the case of repeated, i.e., duplicated pairs \((i_k, j_k)\) only the last one should be used. The default, FALSE, corresponds to the "'>TsparseMatrix" definition.

Value

A sparse matrix, by default (from repr = "C") in compressed, column-oriented form, as an R object inheriting from both '>CsparseMatrix and '>generalMatrix.

Details

Exactly one of the arguments i, j and p must be missing.

In typical usage, p is missing, i and j are vectors of positive integers and x is a numeric vector. These three vectors, which must have the same length, form the triplet representation of the sparse matrix.

If i or j is missing then p must be a non-decreasing integer vector whose first element is zero. It provides the compressed, or “pointer” representation of the row or column indices, whichever is missing. The expanded form of p, rep(seq_along(dp),dp) where dp <- diff(p), is used as the (1-based) row or column indices.

You cannot set both singular and triangular to true; rather use Diagonal() (or its alternatives, see there).

The values of i, j, p and index1 are used to create 1-based index vectors i and j from which a '>TsparseMatrix is constructed, with numerical values given by x, if non-missing. Note that in that case, when some pairs \((i_k,j_k)\) are repeated (aka “duplicated”), the corresponding \(x_k\) are added, in consistency with the definition of the "'>TsparseMatrix" class, unless use.last.ij is set to true. By default, when repr = "C", the '>CsparseMatrix derived from this triplet form is returned, where repr = "R" now allows to directly get an '>RsparseMatrix and repr = "T" leaves the result as '>TsparseMatrix.

The reason for returning a '>CsparseMatrix object instead of the triplet format by default is that the compressed column form is easier to work with when performing matrix operations. In particular, if there are no zeros in x then a '>CsparseMatrix is a unique representation of the sparse matrix.

Examples

Run this code

# NOT RUN {
## simple example
i <- c(1,3:8); j <- c(2,9,6:10); x <- 7 * (1:7)
(A <- sparseMatrix(i, j, x = x))                    ##  8 x 10 "dgCMatrix"
summary(A)
str(A) # note that *internally* 0-based row indices are used

(sA <- sparseMatrix(i, j, x = x, symmetric = TRUE)) ## 10 x 10 "dsCMatrix"
(tA <- sparseMatrix(i, j, x = x, triangular= TRUE)) ## 10 x 10 "dtCMatrix"
stopifnot( all(sA == tA + t(tA)) ,
           identical(sA, as(tA + t(tA), "symmetricMatrix")))

## dims can be larger than the maximum row or column indices
(AA <- sparseMatrix(c(1,3:8), c(2,9,6:10), x = 7 * (1:7), dims = c(10,20)))
summary(AA)

## i, j and x can be in an arbitrary order, as long as they are consistent
set.seed(1); (perm <- sample(1:7))
(A1 <- sparseMatrix(i[perm], j[perm], x = x[perm]))
stopifnot(identical(A, A1))

## The slots are 0-index based, so
try( sparseMatrix(i=A@i, p=A@p, x= seq_along(A@x)) )
## fails and you should say so: 1-indexing is FALSE:
     sparseMatrix(i=A@i, p=A@p, x= seq_along(A@x), index1 = FALSE)

## the (i,j) pairs can be repeated, in which case the x's are summed
(args <- data.frame(i = c(i, 1), j = c(j, 2), x = c(x, 2)))
(Aa <- do.call(sparseMatrix, args))
## explicitly ask for elimination of such duplicates, so
## that the last one is used:
(A. <- do.call(sparseMatrix, c(args, list(use.last.ij = TRUE))))
stopifnot(Aa[1,2] == 9, # 2+7 == 9
          A.[1,2] == 2) # 2 was *after* 7

## for a pattern matrix, of course there is no "summing":
(nA <- do.call(sparseMatrix, args[c("i","j")]))

dn <- list(LETTERS[1:3], letters[1:5])
## pointer vectors can be used, and the (i,x) slots are sorted if necessary:
m <- sparseMatrix(i = c(3,1, 3:2, 2:1), p= c(0:2, 4,4,6), x = 1:6, dimnames = dn)
m
str(m)
stopifnot(identical(dimnames(m), dn))

sparseMatrix(x = 2.72, i=1:3, j=2:4) # recycling x
sparseMatrix(x = TRUE, i=1:3, j=2:4) # recycling x, |--> "lgCMatrix"

## no 'x' --> patter*n* matrix:
(n <- sparseMatrix(i=1:6, j=rev(2:7)))# -> ngCMatrix

## an empty sparse matrix:
(e <- sparseMatrix(dims = c(4,6), i={}, j={}))

## a symmetric one:
(sy <- sparseMatrix(i= c(2,4,3:5), j= c(4,7:5,5), x = 1:5,
                    dims = c(7,7), symmetric=TRUE))
stopifnot(isSymmetric(sy),
          identical(sy, ## switch i <-> j {and transpose }
    t( sparseMatrix(j= c(2,4,3:5), i= c(4,7:5,5), x = 1:5,
                    dims = c(7,7), symmetric=TRUE))))

## rsparsematrix() calls sparseMatrix() :
M1 <- rsparsematrix(1000, 20, nnz = 200)
summary(M1)

## pointers example in converting from other sparse matrix representations.
if(require(SparseM) && packageVersion("SparseM") >= 0.87 &&
   nzchar(dfil <- system.file("extdata", "rua_32_ax.rua", package = "SparseM"))) {
  X <- model.matrix(read.matrix.hb(dfil))
  XX <- sparseMatrix(j = X@ja, p = X@ia - 1L, x = X@ra, dims = X@dimension)
  validObject(XX)

  ## Alternatively, and even more user friendly :
  X. <- as(X, "Matrix")  # or also
  X2 <- as(X, "sparseMatrix")
  stopifnot(identical(XX, X.), identical(X., X2))
}
# }
# NOT RUN {
<!-- % if -->
# }

Run the code above in your browser using DataLab