sparseMatrix {Matrix}  R Documentation 
General Sparse Matrix Construction from Nonzero Entries
Description
Userfriendly construction of sparse matrices (inheriting from
virtual class
CsparseMatrix
,
RsparseMatrix
, or
TsparseMatrix
)
from the positions and values of their nonzero entries.
This interface is recommended over direct construction via
calls such as new("..[CRT]Matrix", ...)
.
Usage
sparseMatrix(i, j, p, x, dims, dimnames,
symmetric = FALSE, triangular = FALSE, index1 = TRUE,
repr = c("C", "R", "T"), giveCsparse,
check = TRUE, use.last.ij = FALSE)
Arguments
i , j 
integer vectors of equal length specifying the positions
(row and column indices) of the nonzero (or non 
p 
integer vector of pointers, one for each column (or row),
to the initial (zerobased) index of elements in the column (or row).
Exactly one of 
x 
optional, typically nonzero values for the matrix entries.
If specified, then the length must equal that of 
dims 
optional length2 integer vector of matrix dimensions.
If missing, then 
dimnames 
optional list of 
symmetric 
logical indicating if the resulting matrix should
be symmetric. In that case, 
triangular 
logical indicating if the resulting matrix should
be triangular. In that case, 
index1 
logical. If 
repr 

giveCsparse 
(deprecated, replaced by 
check 
logical indicating whether to check that the result is
formally valid before returning. Do not set to 
use.last.ij 
logical indicating if, in the case of repeated
(duplicated) pairs 
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
nondecreasing 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 (1based) 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 1based index vectors i
and j
from which a
TsparseMatrix
is constructed, with numerical
values given by x
, if nonmissing. 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.
Value
A sparse matrix, by default in compressed sparse column format and
(formally) without symmetric or triangular structure, i.e.,
by default inheriting from both CsparseMatrix
and generalMatrix
.
Note
You do need to use index1 = FALSE
(or add + 1
to i
and j
) if you want use the 0based i
(and
j
) slots from existing sparse matrices.
See Also
Matrix(*, sparse=TRUE)
for the constructor of
such matrices from a dense matrix. That is easier in small
sample, but much less efficient (or impossible) for large matrices,
where something like sparseMatrix()
is needed.
Further bdiag
and Diagonal
for (block)diagonal and
bandSparse
for banded sparse matrix constructors.
Random sparse matrices via rsparsematrix()
.
The standard R xtabs(*, sparse=TRUE)
, for sparse tables
and sparse.model.matrix()
for building sparse model
matrices.
Consider CsparseMatrix
and similar class
definition help files.
Examples
## 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* 0based 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 0index based, so
try( sparseMatrix(i=A@i, p=A@p, x= seq_along(A@x)) )
## fails and you should say so: 1indexing 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(requireNamespace("SparseM") &&
packageVersion("SparseM") >= "0.87" &&
nzchar(dfil < system.file("extdata", "rua_32_ax.rua", package = "SparseM"))) {
X < SparseM::model.matrix(SparseM::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))
}