pMatrix-class             package:Matrix             R Documentation

_P_e_r_m_u_t_a_t_i_o_n _m_a_t_r_i_c_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     The '"pMatrix"' class is the class of permutation matrices, stored
     as 1-based integer permutation vectors.

_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("pMatrix", ...)'
     or by coercion from an integer permutation vector, see below.

_S_l_o_t_s:


     '_p_e_r_m': An integer, 1-based permutation vector, i.e. an integer
          vector of length 'Dim[1]' whose elements form a permutation
          of '1:Dim[1]'.

     '_D_i_m': Object of class '"integer"'. The dimensions of the matrix
          which must be a two-element vector of equal, non-negative
          integers.

     '_D_i_m_n_a_m_e_s': list of length two; each component containing NULL or
          a 'character' vector length equal the corresponding 'Dim'
          element.

_E_x_t_e_n_d_s:

     Class '"sparseMatrix"' and '"generalMatrix"', directly.

_M_e_t_h_o_d_s:


     %*% 'signature(x = "matrix", y = "pMatrix")' and other signatures
          (use 'showMethods("%*%", class="pMatrix")'): ... 

     _c_o_e_r_c_e 'signature(from = "integer", to = "pMatrix")': This is
          enables typical '"pMatrix"' construction, given a permutation
          vector of '1:n', see the first example.

     _c_o_e_r_c_e 'signature(from = "numeric", to = "pMatrix")': a user
          convenience, to allow 'as(perm, "pMatrix")' for numeric
          'perm' with integer values.

     _c_o_e_r_c_e 'signature(from = "pMatrix", to = "matrix")': coercion to a
          traditional FALSE/TRUE 'matrix' of 'mode' 'logical'. (in
          earlier version of 'Matrix', it resulted in a 0/1-integer
          matrix; 'logical' makes slightly more sense, corresponding
          better to the "natural" sparseMatrix counterpart,
          '"ngTMatrix"'.)

     _c_o_e_r_c_e 'signature(from = "pMatrix", to = "ngTMatrix")': coercion
          to sparse logical matrix of class 'ngTMatrix'.

     _d_e_t_e_r_m_i_n_a_n_t 'signature(x = "pMatrix", logarithm="logical")': Since
          permutation matrices are orthogonal, the determinant must be
          +1 or -1.  In fact, it is exactly the _sign of the
          permutation_.

     _s_o_l_v_e 'signature(a = "pMatrix", b = "missing")': return the
          inverse permutation matrix.

     _t 'signature(x = "pMatrix")': return the transpose of the
          permuation matrix (which is also the inverse of the
          permutation matrix).

_N_o_t_e:

     The inverse of the typical '"pMatrix"' constructor, 'P <- as(ip,
     "pMatrix")' is simply 'ip <- P@perm'.

     Subsetting ("indexing", including, 'diag') '"pMatrix"' objects
     treats themas nonzero-pattern matrices, i.e., as '"ngTMatrix"'
     such that non-matrix subsetting result in 'logical' vectors.
     Sub-assignment ('M[i,j] <- v') is not sensible and hence an error
     for these permutation matrices.

_E_x_a_m_p_l_e_s:

     (pm1 <- as(as.integer(c(2,3,1)), "pMatrix"))
     t(pm1) # is the same as
     solve(pm1)
     pm1 %*% t(pm1) # check that the transpose is the inverse
     stopifnot(all(diag(3) == as(pm1 %*% t(pm1), "matrix")),
               is.logical(as(pm1, "matrix")))

     set.seed(11)
     ## random permutation matrix :
     (p10 <- as(sample(10),"pMatrix"))

     ## Permute rows / columns of a numeric matrix :
     (mm <- round(array(rnorm(3 * 3), c(3, 3)), 2))
     mm %*% pm1
     pm1 %*% mm
     try(as(as.integer(c(3,3,1)), "pMatrix"))# Error: not a permutation

     as(pm1, "ngTMatrix")
     p10[1:7, 1:4] # gives an "ngTMatrix" (most economic!)