man/restore_matrix.rd
9c4d56c4
 \name{restore_matrix}
 \alias{restore_matrix}
 \title{
 Restore the index vector to index matrix in layer_fun
 }
 \description{
 Restore the index vector to index matrix in layer_fun
 }
 \usage{
 restore_matrix(j, i, x, y)
 }
 \arguments{
 
   \item{j}{Column indices directly from \code{layer_fun}.}
   \item{i}{Row indices directly from \code{layer_fun}.}
   \item{x}{Position on x-direction directly from \code{layer_fun}.}
   \item{y}{Position on y-direction directly from \code{layer_fun}.}
 
 }
 \details{
 The values that are sent to \code{layer_fun} are all vectors (for the vectorization
 of the grid graphic functions), however, the heatmap slice where
 \code{layer_fun} is applied to, is still represented by a matrix, thus, it would be
 very convinient if all the arguments in \code{layer_fun} can be converted to the
 sub-matrix for the current slice. Here, as shown in above example,
 \code{\link{restore_matrix}} does the job. \code{\link{restore_matrix}} directly accepts the first
 four argument in \code{layer_fun} and returns an index matrix, where rows and
 columns correspond to the rows and columns in the current slice, from top to
 bottom and from left to right. The values in the matrix are the natural order
 of e.g. vector \code{j} in current slice.
 
 For following code:
 
   \preformatted{
     Heatmap(small_mat, name = "mat", col = col_fun,
         row_km = 2, column_km = 2,
         layer_fun = function(j, i, x, y, w, h, fill) \{
             ind_mat = restore_matrix(j, i, x, y)
             print(ind_mat)
         \}
     )  }
 
 The first output which is for the top-left slice:
 
   \preformatted{
          [,1] [,2] [,3] [,4] [,5]
     [1,]    1    4    7   10   13
     [2,]    2    5    8   11   14
     [3,]    3    6    9   12   15  }
 
 As you see, this is a three-row and five-column index matrix where the first
 row corresponds to the top row in the slice. The values in the matrix
 correspond to the natural index (i.e. 1, 2, ...) in \code{j}, \code{i}, \code{x}, \code{y},
 ... in \code{layer_fun}. Now, if we want to add values on the second column in the
 top-left slice, the code which is put inside \code{layer_fun} would look like:
 
   \preformatted{
     for(ind in ind_mat[, 2]) \{
         grid.text(small_mat[i[ind], j[ind]], x[ind], y[ind], ...)
     \}  }
 }
 \examples{
 set.seed(123)
 mat = matrix(rnorm(81), nr = 9)
 Heatmap(mat, row_km = 2, column_km = 2,
     layer_fun = function(j, i, x, y, width, height, fill) {
        ind_mat = restore_matrix(j, i, x, y)
        print(ind_mat)
 })
 
 set.seed(123)
 mat = matrix(round(rnorm(81), 2), nr = 9)
 Heatmap(mat, row_km = 2, column_km = 2,
     layer_fun = function(j, i, x, y, width, height, fill) {
        ind_mat = restore_matrix(j, i, x, y)
        ind = unique(c(ind_mat[2, ], ind_mat[, 3]))
        grid.text(pindex(mat, i[ind], j[ind]), x[ind], y[ind])
 })
 }