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, index1 = 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.
`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.

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

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

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

[Package Matrix version 0.999375-33 Index]