R: General Sparse Matrix Construction from Nonzero Entries

sparseMatrix {Matrix} | R Documentation

## General Sparse Matrix Construction from Nonzero Entries

### Description

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.

### Usage

    sparseMatrix(i = ep, j = ep, p, x, dims, dimnames,
                 symmetric = FALSE, index1 = TRUE,
                 giveCsparse = TRUE, check = TRUE)

### 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.
`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.
`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).
`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.
`giveCsparse` | logical indicating if the result should be a `CsparseMatrix` or a `TsparseMatrix`. The default, `TRUE` is very often 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!

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

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 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 (see `giveCsparse`) in compressed, column-oriented form, as an R object inheriting from both `CsparseMatrix` and `generalMatrix`.

### See Also

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

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

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

    ## pointers example in converting from other sparse matrix representations.
    if(require(SparseM) && packageVersion("SparseM") >= 0.87 &&
       nzchar(dfil <- system.file("textdata", "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))
    }

[Package Matrix version 1.0-6 Index]