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.

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

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.

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

dims

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

.

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 *repr*esentation to
be used for the result, i.e., one from the super classes
`'>CsparseMatrix`

, `'>TsparseMatrix`

, or
`'>RsparseMatrix`

.

giveCsparse

check

logical indicating if a validity check is performed; do
not set to `FALSE`

unless you know what you're doing!

A sparse matrix, by default (from `repr = "C"`

) in compressed,
column-oriented form, as an R object inheriting from both
`'>CsparseMatrix`

and `'>generalMatrix`

.

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.

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

# 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 DataCamp Workspace