iam                   package:VGAM                   R Documentation

_I_n_d_e_x _f_r_o_m _A_r_r_a_y _t_o _M_a_t_r_i_x

_D_e_s_c_r_i_p_t_i_o_n:

     Maps the elements of an array containing symmetric
     positive-definite matrices to a matrix with sufficient columns to
     hold them  (called matrix-band format.)

_U_s_a_g_e:

     iam(j, k, M, hbw = M, both = FALSE, diagonal = TRUE)

_A_r_g_u_m_e_n_t_s:

       j: An integer from the set {'1:M'} giving the row number  of an
          element.

       k: An integer from the set {'1:M'} giving the column number  of
          an element.

       M: The number of linear/additive predictors. This is the
          dimension of each positive-definite symmetric matrix. 

     hbw: Defunct. 

    both: Logical. Return both the row and column indices?  See below
          for more details. 

diagonal: Logical. Return the indices for the diagonal elements?  If
          'FALSE' then only the strictly upper triangular part of the
          matrix  elements are used. 

_D_e_t_a_i_l_s:

     Suppose we have n symmetric positive-definite square matrices,
     each M by M, and  these are stored in an 'array' of dimension
     'c(n,M,M)'. Then these can be more compactly represented by a 
     'matrix' of dimension 'c(n,K)' where 'K' is an integer between 'M'
     and 'M*(M+1)/2' inclusive.  The mapping between these two
     representations is given by this function. It firstly enumerates
     by the diagonal elements, followed by the band immediately above
     the diagonal, then the band above that one, etc.  The last element
     is '(1,M)'. This function performs the mapping from elements
     '(j,k)' of symmetric positive-definite square matrices to the
     columns of another matrix representing such. This is called the
     _matrix-band_ format and is used by  the 'VGAM' package.

_V_a_l_u_e:

     This function has a dual purpose depending on the value of 'both'.
     If 'both=FALSE' then the column number corresponding to the
     'j'-'k' element of the matrix is returned. If 'both=TRUE' then 'j'
     and 'k' are ignored and a list with the following components are
     returned.  

row.index: The row indices of the upper triangular part of the matrix
          (This may or may not include the diagonal elements, depending
          on the argument 'diagonal'). 

col.index: The column indices of the upper triangular part of the
          matrix (This may or may not include the diagonal elements,
          depending on the argument 'diagonal').  

_N_o_t_e:

     This function is used in the 'weight' slot of many 'VGAM' family
     functions (see 'vglmff-class'), especially those whose M is
     determined by the data, e.g., 'dirichlet', 'multinomial'.

_A_u_t_h_o_r(_s):

     T. W. Yee

_R_e_f_e_r_e_n_c_e_s:

     The website <URL: http://www.stat.auckland.ac.nz/~yee> contains
     some additional information.

_S_e_e _A_l_s_o:

     'vglmff-class'.

_E_x_a_m_p_l_e_s:

     iam(1, 2, M=3) # The 4th column represents element (1,2) of a 3x3 matrix
     iam(NULL, NULL, M=3, both=TRUE) # Return the row & column indices

     dirichlet()@weight

     M = 4
     temp1 = iam(NA, NA, M=M, both=TRUE)
     mat1 = matrix(NA, M, M)
     mat1[cbind(temp1$row, temp1$col)] = 1:length(temp1$row)
     mat1 # More commonly used

     M = 4
     temp2 = iam(NA, NA, M=M, both=TRUE, diagonal=FALSE)
     mat2 = matrix(NA, M, M)
     mat2[cbind(temp2$row, temp2$col)] = 1:length(temp2$row)
     mat2 # Rarely used

