heatmap                 package:mva                 R Documentation

_D_r_a_w _a _H_e_a_t _M_a_p

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

     A heat map is a false color image (basically 'image(t(x))') with a
     dendrogram added to the left side and to the top.  Typically,
     reordering of the rows and columns according to some set of values
     (row or column means) within the restrictions imposed by the
     dendrogram is carried out.

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

     heatmap(x, Rowv=NULL, Colv=if(symm)"Rowv" else NULL,
             distfun = dist, hclustfun = hclust, add.expr,
             symm = FALSE, revC = identical(Colv, "Rowv"),
             scale=c("row", "column", "none"), na.rm = TRUE,
             margins = c(5, 5), ColSideColors, RowSideColors,
             cexRow = 0.2 + 1/log10(nr), cexCol = 0.2 + 1/log10(nc),
             labRow = NULL, labCol = NULL, main = NULL, xlab = NULL, ylab = NULL,
             ...)

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

       x: numeric matrix of the values to be plotted. 

    Rowv: determines if and how the _row_ dendrogram should be
          reordered.  Either a 'dendrogram' or a vector of values used
          to reorder the row dendrogram or 'FALSE' to suppress
          reordering or by default, 'NULL', see _Details_ below.

    Colv: determines if and how the _column_ dendrogram should be
          reordered.  Has the options as the 'Rowv' argument above and
          _additionally_ when 'x' is a square matrix, 'Colv = "Rowv"'
          means that columns should be treated identically to the rows.

 distfun: function used to compute the distance (dissimilarity) between
          both rows and columns.  Defaults to 'dist'.

hclustfun: function used to compute the hierarchical clustering when
          'Rowv' or 'Colv' are not dendrograms.  Defaults to 'hclust'.

add.expr: expression that will be evaluated after the call to 'image'. 
          Can be used to add components to the plot.

    symm: logical indicating if 'x' should be treated *symm*etrically;
          can only be true when 'x' is a square matrix.

    revC: logical indicating if the column order should be 'rev'ersed
          for plotting, such that e.g., for the symmetric case, the
          symmetry axis is as usual.

   scale: character indicating if the values should be centered and
          scaled in either the row direction or the column direction,
          or none.  The default is '"row"' if 'symm' false, and
          '"none"' otherwise.

   na.rm: logical indicating whether 'NA''s should be removed.

 margins: numeric vector of length 2 containing the margins (see
          'par(mar= *)') for column and row names, respectively.

ColSideColors: (optional) character vector of length 'ncol(x)'
          containing the color names for a horizontal side bar that may
          be used to annotate the columns of 'x'.

RowSideColors: (optional) character vector of length 'nrow(x)'
          containing the color names for a vertical side bar that may
          be used to annotate the rows of 'x'.

cexRow, cexCol: positive numbers, used as 'cex.axis' in for the row or
          column axis labeling.  The defaults currently only use number
          of rows or columns, respectively.

labRow, labCol: character vectors with row and column labels to use;
          these default to 'rownames(x)' or 'colnames(x)',
          respectively.

main, xlab, ylab: main, x- and y-axis titles; defaults to none.

     ...: additional arguments passed on to 'image', e.g., 'col'
          specifying the colors.

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

     If either 'Rowv' or 'Colv' are dendrograms they are honored (and
     not reordered).  Otherwise, dendrograms are computed as 'dd <-
     as.dendrogram(hclustfun(distfun(X)))' where 'X' is either 'x' or
     't(x)'.

     If either is a vector (of "weights") then the appropriate
     dendrogram is reordered according to the supplied values subject
     to the constraints imposed by the dendrogram, by 'reorder(dd,
     Rowv)', in the row case. If either is missing, as by default, then
     the ordering of the corresponding dendrogram is by the mean value
     of the rows/columns, i.e., in the case of rows, 'Rowv <-
     rowMeans(x, na.rm=na.rm)'. If either is 'NULL', _no reordering_
     will be done for the corresponding side.

     By default ('scale = "row"') the rows are scaled to have mean zero
     and standard deviation one.  There is some empirical evidence from
     genomic plotting that this is useful.

     The default colors are not pretty.  Consider using enhancements
     such as the 'RColorBrewer' package, <URL:
     http://cran.r-project.org/src/contrib/PACKAGES.html#RColorBrewer>.

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

     Invisibly, a list with components 

  rowInd: *r*ow index permutation vector as returned by
          'order.dendrogram'.

  colInd: *c*olumn index permutation vector.

_N_o_t_e:

     The original rows and columns are reordered _in any case_ to match
     the dendrogram, e.g., the rows by 'order.dendrogram(Rowv)' where
     'Rowv' is the (possibly 'reorder()'ed) row dendrogram.

     'heatmap()' uses 'layout' and draws the 'image' in the lower right
     corner of a 2x2 layout. Consequentially, it can *not* be used in a
     multi column/row layout, i.e., when 'par(mfrow= *)' or '(mfcol=
     *)' has been called.

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

     Andy Liaw, original; R. Gentleman, M. Maechler, W. Huber,
     revisions.

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

     'image', 'hclust'

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

      data(mtcars)
      x  <- as.matrix(mtcars)
      rc <- rainbow(nrow(x), start=0, end=.3)
      cc <- rainbow(ncol(x), start=0, end=.3)
      hv <- heatmap(x, col = cm.colors(256), scale="column",
                    RowSideColors = rc, ColSideColors = cc, margin=c(5,10),
                    xlab = "specification variables", ylab= "Car Models",
                    main = "heatmap(<Mtcars data>, ..., scale = \"column\")")
      str(hv) # the two re-ordering index vectors

      data(attitude)
      round(Ca <- cor(attitude), 2)
      symnum(Ca) # simple graphic
      heatmap(Ca,             symm = TRUE, margin=c(6,6))# with reorder()
      heatmap(Ca, Rowv=FALSE, symm = TRUE, margin=c(6,6))# _NO_ reorder()

      ## For variable clustering, rather use distance based on cor():
      data(USJudgeRatings)
      symnum( cU <- cor(USJudgeRatings) )

      hU <- heatmap(cU, Rowv = FALSE, symm = TRUE, col = topo.colors(16),
                   distfun = function(c) as.dist(1 - c))
      ## The Correlation matrix with same reordering:
      round(100 * cU[hU[[1]], hU[[2]]])

