sparseMatrix: General Sparse Matrix Construction from Nonzero Entries

Description Usage Arguments Details Value Note See Also Examples

View source: R/sparseMatrix.R

Description

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.

Usage

1
2
3
4
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)

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

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

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 representation to be used for the result, i.e., one from the super classes CsparseMatrix, TsparseMatrix, or RsparseMatrix.

giveCsparse

(deprecated, replaced with repr): logical indicating if the result should be a CsparseMatrix or a TsparseMatrix, where the default was TRUE, and now is determined from repr; very often Csparse matrices are 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!

use.last.ij

logical indicating if in the case of repeated, i.e., duplicated pairs (i_k, j_k) only the last one should be used. The default, FALSE, corresponds to the "TsparseMatrix" definition.

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.

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.

Value

A sparse matrix, by default (from repr = "C") in compressed, column-oriented form, as an R object 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 0-based 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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
## 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))
}

Example output

8 x 10 sparse Matrix of class "dgCMatrix"
                             
[1,] . 7 . . .  .  .  .  .  .
[2,] . . . . .  .  .  .  .  .
[3,] . . . . .  .  .  . 14  .
[4,] . . . . . 21  .  .  .  .
[5,] . . . . .  . 28  .  .  .
[6,] . . . . .  .  . 35  .  .
[7,] . . . . .  .  .  . 42  .
[8,] . . . . .  .  .  .  . 49
8 x 10 sparse Matrix of class "dgCMatrix", with 7 entries 
  i  j  x
1 1  2  7
2 4  6 21
3 5  7 28
4 6  8 35
5 3  9 14
6 7  9 42
7 8 10 49
Formal class 'dgCMatrix' [package "Matrix"] with 6 slots
  ..@ i       : int [1:7] 0 3 4 5 2 6 7
  ..@ p       : int [1:11] 0 0 1 1 1 1 2 3 4 6 ...
  ..@ Dim     : int [1:2] 8 10
  ..@ Dimnames:List of 2
  .. ..$ : NULL
  .. ..$ : NULL
  ..@ x       : num [1:7] 7 21 28 35 14 42 49
  ..@ factors : list()
10 x 10 sparse Matrix of class "dsCMatrix"
                                 
 [1,] . 7  .  .  .  .  .  .  .  .
 [2,] 7 .  .  .  .  .  .  .  .  .
 [3,] . .  .  .  .  .  .  . 14  .
 [4,] . .  .  .  . 21  .  .  .  .
 [5,] . .  .  .  .  . 28  .  .  .
 [6,] . .  . 21  .  .  . 35  .  .
 [7,] . .  .  . 28  .  .  . 42  .
 [8,] . .  .  .  . 35  .  .  . 49
 [9,] . . 14  .  .  . 42  .  .  .
[10,] . .  .  .  .  .  . 49  .  .
10 x 10 sparse Matrix of class "dtCMatrix"
                              
 [1,] . 7 . . .  .  .  .  .  .
 [2,] . . . . .  .  .  .  .  .
 [3,] . . . . .  .  .  . 14  .
 [4,] . . . . . 21  .  .  .  .
 [5,] . . . . .  . 28  .  .  .
 [6,] . . . . .  .  . 35  .  .
 [7,] . . . . .  .  .  . 42  .
 [8,] . . . . .  .  .  .  . 49
 [9,] . . . . .  .  .  .  .  .
[10,] . . . . .  .  .  .  .  .
10 x 20 sparse Matrix of class "dgCMatrix"
                                                  
 [1,] . 7 . . .  .  .  .  .  . . . . . . . . . . .
 [2,] . . . . .  .  .  .  .  . . . . . . . . . . .
 [3,] . . . . .  .  .  . 14  . . . . . . . . . . .
 [4,] . . . . . 21  .  .  .  . . . . . . . . . . .
 [5,] . . . . .  . 28  .  .  . . . . . . . . . . .
 [6,] . . . . .  .  . 35  .  . . . . . . . . . . .
 [7,] . . . . .  .  .  . 42  . . . . . . . . . . .
 [8,] . . . . .  .  .  .  . 49 . . . . . . . . . .
 [9,] . . . . .  .  .  .  .  . . . . . . . . . . .
[10,] . . . . .  .  .  .  .  . . . . . . . . . . .
10 x 20 sparse Matrix of class "dgCMatrix", with 7 entries 
  i  j  x
1 1  2  7
2 4  6 21
3 5  7 28
4 6  8 35
5 3  9 14
6 7  9 42
7 8 10 49
[1] 2 3 6 4 1 7 5
8 x 10 sparse Matrix of class "dgCMatrix"
                             
[1,] . 7 . . .  .  .  .  .  .
[2,] . . . . .  .  .  .  .  .
[3,] . . . . .  .  .  . 14  .
[4,] . . . . . 21  .  .  .  .
[5,] . . . . .  . 28  .  .  .
[6,] . . . . .  .  . 35  .  .
[7,] . . . . .  .  .  . 42  .
[8,] . . . . .  .  .  .  . 49
Error in validObject(r) : 
  invalid class "dgTMatrix" object: all row indices (slot 'i') must be between 0 and nrow-1 in a TsparseMatrix
8 x 10 sparse Matrix of class "dgCMatrix"
                        
[1,] . 1 . . . . . . . .
[2,] . . . . . . . . . .
[3,] . . . . . . . . 5 .
[4,] . . . . . 2 . . . .
[5,] . . . . . . 3 . . .
[6,] . . . . . . . 4 . .
[7,] . . . . . . . . 6 .
[8,] . . . . . . . . . 7
  i  j  x
1 1  2  7
2 3  9 14
3 4  6 21
4 5  7 28
5 6  8 35
6 7  9 42
7 8 10 49
8 1  2  2
8 x 10 sparse Matrix of class "dgCMatrix"
                             
[1,] . 9 . . .  .  .  .  .  .
[2,] . . . . .  .  .  .  .  .
[3,] . . . . .  .  .  . 14  .
[4,] . . . . . 21  .  .  .  .
[5,] . . . . .  . 28  .  .  .
[6,] . . . . .  .  . 35  .  .
[7,] . . . . .  .  .  . 42  .
[8,] . . . . .  .  .  .  . 49
8 x 10 sparse Matrix of class "dgCMatrix"
                             
[1,] . 2 . . .  .  .  .  .  .
[2,] . . . . .  .  .  .  .  .
[3,] . . . . .  .  .  . 14  .
[4,] . . . . . 21  .  .  .  .
[5,] . . . . .  . 28  .  .  .
[6,] . . . . .  .  . 35  .  .
[7,] . . . . .  .  .  . 42  .
[8,] . . . . .  .  .  .  . 49
8 x 10 sparse Matrix of class "ngCMatrix"
                        
[1,] . | . . . . . . . .
[2,] . . . . . . . . . .
[3,] . . . . . . . . | .
[4,] . . . . . | . . . .
[5,] . . . . . . | . . .
[6,] . . . . . . . | . .
[7,] . . . . . . . . | .
[8,] . . . . . . . . . |
3 x 5 sparse Matrix of class "dgCMatrix"
  a b c d e
A . 2 . . 6
B . . 4 . 5
C 1 . 3 . .
Formal class 'dgCMatrix' [package "Matrix"] with 6 slots
  ..@ i       : int [1:6] 2 0 1 2 0 1
  ..@ p       : int [1:6] 0 1 2 4 4 6
  ..@ Dim     : int [1:2] 3 5
  ..@ Dimnames:List of 2
  .. ..$ : chr [1:3] "A" "B" "C"
  .. ..$ : chr [1:5] "a" "b" "c" "d" ...
  ..@ x       : num [1:6] 1 2 4 3 6 5
  ..@ factors : list()
3 x 4 sparse Matrix of class "dgCMatrix"
                     
[1,] . 2.72 .    .   
[2,] . .    2.72 .   
[3,] . .    .    2.72
3 x 4 sparse Matrix of class "lgCMatrix"
            
[1,] . | . .
[2,] . . | .
[3,] . . . |
6 x 7 sparse Matrix of class "ngCMatrix"
                  
[1,] . . . . . . |
[2,] . . . . . | .
[3,] . . . . | . .
[4,] . . . | . . .
[5,] . . | . . . .
[6,] . | . . . . .
4 x 6 sparse Matrix of class "ngCMatrix"
                
[1,] . . . . . .
[2,] . . . . . .
[3,] . . . . . .
[4,] . . . . . .
7 x 7 sparse Matrix of class "dsCMatrix"
                  
[1,] . . . . . . .
[2,] . . . 1 . . .
[3,] . . . . . 3 .
[4,] . 1 . . 4 . 2
[5,] . . . 4 5 . .
[6,] . . 3 . . . .
[7,] . . . 2 . . .
1000 x 20 sparse Matrix of class "dgCMatrix", with 200 entries 
      i  j       x
1   261  1 -1.1000
2   268  1 -0.8000
3   466  1 -1.1000
4   707  1  2.2000
5   174  2 -0.2000
6   236  2 -1.3000
7   267  2  1.5000
8   411  2 -1.3000
9   495  2  1.0000
10  532  2  0.4100
11  680  2  0.7100
12  985  2 -0.0970
13  999  2 -0.2300
14   53  3  1.5000
15   85  3 -1.1000
16  156  3  0.6900
17  187  3 -0.2100
18  425  3  0.5300
19  510  3 -0.1200
20  575  3  0.5900
21  855  3  0.1600
22  949  3  0.0370
23  449  4  1.4000
24  479  4  0.0056
25  531  4 -0.5000
26  588  4  1.5000
27  591  4  0.4200
28  720  4  1.5000
29  751  4  0.6200
30  792  4 -0.3000
31   39  5 -0.5900
32  119  5  1.6000
33  126  5  1.6000
34  222  5 -0.0830
35  240  5  0.4900
36  244  5  1.3000
37  331  5  0.3800
38  546  5 -1.5000
39  746  5 -0.1600
40  773  5 -0.7400
41  885  5  1.5000
42  890  5 -0.0900
43  129  6  0.5000
44  146  6  2.7000
45  299  6  0.3900
46  327  6 -0.1200
47  340  6  0.2000
48  380  6 -0.4900
49  514  6  0.0820
50  612  6  1.6000
51  653  6  0.6100
52  824  6  1.3000
53  857  6 -0.0130
54  299  7  0.5500
55  310  7  2.4000
56  483  7 -0.0700
57  528  7  0.0430
58  630  7  0.3200
59  654  7  1.9000
60  657  7  0.7000
61  698  7 -1.9000
62  761  7  0.8900
63  800  7  1.5000
64  912  7 -1.0000
65   31  8 -0.3900
66   98  8 -0.5000
67  547  8  1.7000
68  597  8  1.1000
69  641  8 -1.1000
70  680  8 -0.4100
71  707  8  0.0630
72  716  8 -1.1000
73  763  8  0.3100
74  773  8 -0.9500
75  970  8 -1.4000
76  116  9 -0.8700
77  165  9  0.9600
78  198  9 -1.1000
79  213  9 -1.2000
80  584  9  0.9300
81  662  9 -0.2100
82  743  9 -1.2000
83  856  9  0.1100
84  877  9  1.2000
85  989  9  1.6000
86  997  9 -1.6000
87   25 10  0.2800
88   65 10 -0.7000
89  157 10 -0.3700
90  496 10 -0.9300
91  515 10  0.7800
92  526 10 -1.0000
93  532 10 -0.4500
94  543 10  1.7000
95  631 10  0.2600
96  632 10 -1.6000
97  856 10  0.8500
98  859 10 -0.0037
99  936 10  0.4900
100 951 10  0.0250
101 979 10  0.9500
102  86 11  1.7000
103 163 11 -0.1900
104 236 11 -0.0120
105 269 11  0.6700
106 347 11  0.8900
107 453 11 -0.9800
108 514 11  1.9000
109 575 11  0.0690
110 854 11 -0.2100
111  41 12  0.7400
112  63 12 -0.1000
113 144 12  2.0000
114 146 12  1.5000
115 427 12 -0.9500
116 701 12 -1.8000
117 842 12 -0.1400
118 886 12 -0.1500
119 915 12 -0.3700
120 951 12 -0.7100
121 977 12 -1.2000
122   3 13  0.6200
123  44 13 -1.1000
124 206 13 -0.9800
125 506 13 -0.5900
126 582 13  0.5800
127 609 13 -0.9000
128 731 13 -1.5000
129 775 13 -1.5000
130 778 13 -1.2000
131 792 13  1.1000
132 920 13 -0.8700
133 981 13 -0.4900
134  24 14  0.1400
135  34 14  0.0180
136 207 14 -0.2500
137 216 14 -1.1000
138 351 14  0.8000
139 565 14 -0.2600
140 738 14  1.7000
141 826 14 -1.1000
142 105 15 -1.3000
143 167 15  0.9800
144 198 15 -0.5700
145 234 15 -0.2400
146 346 15  0.0270
147 358 15  2.5000
148 360 15  0.3700
149 452 15 -0.9600
150 487 15 -1.0000
151 560 15 -0.0610
152 617 15 -0.7700
153 696 15 -0.3100
154 830 15 -2.9000
155   9 16 -0.5400
156  27 16  0.5100
157  84 16 -0.4300
158 281 16  0.7800
159 392 16 -0.9700
160 479 16  0.3500
161 492 16  0.6000
162 507 16 -0.7000
163 511 16  0.1600
164 540 16 -1.1000
165 632 16 -0.9100
166 758 16 -0.3200
167 862 16 -0.9700
168 877 16  2.0000
169 144 17  1.8000
170 392 17 -0.9600
171 526 17 -0.4800
172 651 17  0.0700
173 675 17 -1.7000
174 736 17 -0.3500
175 982 17 -0.4200
176 169 18  1.5000
177 187 18  0.4700
178 228 18 -0.6100
179 376 18  1.6000
180 386 18 -1.1000
181 451 18 -0.0170
182 453 18 -0.5400
183 475 18  0.5500
184 574 18 -1.6000
185 759 18 -0.4400
186 765 18 -0.8900
187 784 18 -0.2900
188 907 18  0.1800
189 210 19  0.5800
190 374 19  0.6400
191 389 19  1.6000
192 455 19 -0.0620
193 682 19  0.3400
194 704 19  1.7000
195 144 20 -1.5000
196 423 20  0.8200
197 573 20  0.5000
198 725 20  0.0950
199 759 20 -1.0000
200 829 20 -1.7000
Loading required package: SparseM

Attaching package: 'SparseM'

The following object is masked from 'package:base':

    backsolve

Matrix documentation built on May 4, 2021, 5:05 p.m.