iam {VGAM} | R Documentation

## Index from Array to Matrix

### Description

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

### Usage

    iam(j, k, M, both = FALSE, diag = TRUE)

### Arguments

`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.
`both` | Logical. Return both the row and column indices? See below for more details.
`diag` | Logical. Return the indices for the diagonal elements? If `FALSE` then only the strictly upper triangular part of the matrix elements are used.

### Details

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.

### Value

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

### Note

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

### Author(s)

T. W. Yee

### See Also

`vglmff-class`.

### Examples

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

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

[Package VGAM version 1.0-3 Index]