sparseMatrix             package:Matrix             R Documentation

_G_e_n_e_r_a_l _S_p_a_r_s_e _M_a_t_r_i_x _C_o_n_s_t_r_u_c_t_i_o_n _f_r_o_m _N_o_n_z_e_r_o _E_n_t_r_i_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

     sparseMatrix(i = ep, j = ep, p, x, dims, dimnames, index1 = TRUE)

_A_r_g_u_m_e_n_t_s:

     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 patter*n* 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.

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

     A sparse matrix in compressed, column-oriented form, as an R
     object inheriting from both 'CsparseMatrix' and 'generalMatrix'.

_S_e_e _A_l_s_o:

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

_E_x_a_m_p_l_e_s:

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