sparseMatrix {Matrix} | R Documentation |
User friendly construction of a compressed, column-oriented, sparse
matrix, inheriting from class
CsparseMatrix
, from locations (and values) of its
nonzero entries.
This is the recommended user interface rather than direct
new("***Matrix", ....)
calls.
sparseMatrix(i = ep, j = ep, p, x, dims, dimnames, index1 = TRUE)
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. |
p |
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. |
x |
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. |
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. |
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.
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. The
CsparseMatrix
derived from this triplet form is
returned.
The reason for returning a CsparseMatrix
object
instead of the triplet format 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.
A sparse matrix in compressed, column-oriented form, as an R object
inheriting from both CsparseMatrix
and
generalMatrix
.
Matrix(*, sparse=TRUE)
for the more usual
constructor of such matrices; further bdiag
and
Diagonal
for (block-)diagonal and
bandSparse
for banded sparse matrix constructors.
Consider CsparseMatrix
and similar class
definition help files.
## simple example i <- c(1,3:8); j <- c(2,9,6:10); x <- 7 * (1:7) (A <- sparseMatrix(i, j, x = x)) summary(A) str(A) # note that *internally* 0-based row indices are used ## 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 (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)) ## 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) m str(m) 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={})) ## pointers example in converting from other sparse matrix representations. if(require(SparseM)) { X <- model.matrix(read.matrix.hb(system.file("data", "rua_32_ax.rua", package = "SparseM"))) 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)) }