nsparseMatrix-classes         package:Matrix         R Documentation

_S_p_a_r_s_e "_p_a_t_t_e_r_n" _M_a_t_r_i_c_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     The 'nsparseMatrix' class is a virtual class of sparse _"pattern"_
     matrices, i.e., binary matrices conceptually with 'TRUE'/'FALSE'
     entries.  Only the positions of the elements that are 'TRUE' are
     stored.  These can be stored in the ``triplet'' form (classes
     'ngTMatrix', 'nsTMatrix', and 'ntTMatrix' which really contain
     pairs, not triplets) or in compressed column-oriented form
     (classes 'ngCMatrix', 'nsCMatrix', and 'ntCMatrix') or in
     compressed row-oriented form (classes 'ngRMatrix', 'nsRMatrix',
     and 'ntRMatrix').  The second letter in the name of these
     non-virtual classes indicates 'g'eneral, 's'ymmetric, or
     't'riangular.

_O_b_j_e_c_t_s _f_r_o_m _t_h_e _C_l_a_s_s:

     Objects can be created by calls of the form 'new("ngCMatrix",
     ...)' and so on.  More frequently objects are created by coercion
     of a numeric sparse matrix to the pattern form for use in the
     symbolic analysis phase of an algorithm involving sparse matrices.
      Such algorithms often involve two phases: a symbolic phase
     wherein the positions of the non-zeros in the result are
     determined and a numeric phase wherein the actual results are
     calculated.  During the symbolic phase only the positions of the
     non-zero elements in any operands are of interest, hence numeric
     sparse matrices can be treated as sparse pattern matrices.

_S_l_o_t_s:


     '_u_p_l_o': Object of class '"character"'. Must be either "U", for
          upper triangular, and "L", for lower triangular. Present in
          the triangular and symmetric classes but not in the general
          class.

     '_d_i_a_g': Object of class '"character"'. Must be either '"U"', for
          unit triangular (diagonal is all ones), or '"N"' for
          non-unit.  The implicit diagonal elements are not explicitly
          stored when 'diag' is '"U"'.  Present in the triangular
          classes only.

     '_p': Object of class '"integer"' of pointers, one for each column
          (row), to the initial (zero-based) index of elements in the
          column.  Present in compressed column-oriented and compressed
          row-oriented forms only.

     '_i': Object of class '"integer"' of length nnzero (number of
          non-zero elements).  These are the row numbers for each TRUE
          element in the matrix.  All other elements are FALSE. Present
          in triplet and compressed column-oriented forms only.

     '_j': Object of class '"integer"' of length nnzero (number of
          non-zero elements).  These are the column numbers for each
          TRUE element in the matrix.  All other elements are FALSE.
          Present in triplet and compressed column-oriented forms only.

     '_D_i_m': Object of class '"integer"' - the dimensions of the matrix.

_M_e_t_h_o_d_s:


     _c_o_e_r_c_e 'signature(from = "dgCMatrix", to = "ngCMatrix")', and many
          similar ones; typically you should coerce to
          '"nsparseMatrix"' (or '"nMatrix"').  Note that coercion to a
          sparse pattern matrix records all the potential non-zero
          entries, i.e., explicit ("non-structural") zeroes are coerced
          to 'TRUE', not 'FALSE', see the example.

     _t 'signature(x = "ngCMatrix")': returns the transpose of 'x'

_S_e_e _A_l_s_o:

     the class 'dgCMatrix'

_E_x_a_m_p_l_e_s:

     (m <- Matrix(c(0,0,2:0), 3,5, dimnames=list(LETTERS[1:3],NULL)))
     ## ``extract the nonzero-pattern of (m) into an nMatrix'':
     nm <- as(m, "nsparseMatrix") ## -> will be a "ngCMatrix"
     str(nm) # no 'x' slot
     nnm <- !nm     # no longer sparse
     (nnm <- as(nnm, "sparseMatrix"))# "lgCMatrix"
     ## consistency check:
     stopifnot(xor(as( nm, "matrix"),
                   as(nnm, "matrix")))

     ## low-level way of adding "non-structural zeros" :
     nnm@x[2:4] <- c(FALSE,NA,NA)
     nnm
     as(nnm, "nMatrix") # NAs *and* non-structural 0  |--->  'TRUE'

     data(KNex)
     nmm <- as(KNex $ mm, "ngCMatrix")
     str(xlx <- crossprod(nmm))# "nsCMatrix"
     stopifnot(isSymmetric(xlx))
     image(xlx, main=paste("crossprod(nmm) : Sparse", class(xlx)))