heatmap
Draw a Heat Map
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.
 Keywords
 hplot
Usage
heatmap(x, Rowv = NULL, Colv = if(symm)"Rowv" else NULL, distfun = dist, hclustfun = hclust, reorderfun = function(d, w) reorder(d, w), 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, keep.dendro = FALSE, verbose = getOption("verbose"), ...)
Arguments
 x
 numeric matrix of the values to be plotted.
 Rowv
 determines if and how the row dendrogram should be
computed and reordered. Either a
dendrogram
or a vector of values used to reorder the row dendrogram orNA
to suppress any row dendrogram (and reordering) or by default,NULL
, see ‘Details’ below.  Colv
 determines if and how the column dendrogram should be
reordered. Has the same options as the
Rowv
argument above and additionally whenx
is a square matrix,Colv = "Rowv"
means that columns should be treated identically to the rows (and so if there is to be no row dendrogram there will not be a column one either).  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
orColv
are not dendrograms. Defaults tohclust
. Should take as argument a result ofdistfun
and return an object to whichas.dendrogram
can be applied.  reorderfun
function(d, w)
of dendrogram and weights for reordering the row and column dendrograms. The default usesreorder.dendrogram
. 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 symmetrically; can only be true whenx
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"
ifsymm
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 ofx
.  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 ofx
.  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)
orcolnames(x)
, respectively.  main, xlab, ylab
 main, x and yaxis titles; defaults to none.
 keep.dendro
 logical indicating if the dendrogram(s) should be
kept as part of the result (when
Rowv
and/orColv
are not NA).  verbose
 logical indicating if information should be printed.
 ...
 additional arguments passed on to
image
, e.g.,col
specifying the colors.
Details
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 NA
, 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 \href{https://CRAN.Rproject.org/package=#1}{\pkg{#1}}RColorBrewerRColorBrewer package.
Value

Invisibly, a list with components
 rowInd
 row index permutation vector as returned by
order.dendrogram
.  colInd
 column index permutation vector.
 Rowv
 the row dendrogram; only if input
Rowv
was not NA andkeep.dendro
is true.  Colv
 the column dendrogram; only if input
Colv
was not NA andkeep.dendro
is true.
Note
Unless Rowv = NA
(or Colw = NA
), 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.
See Also
Examples
library(stats)
require(graphics); require(grDevices)
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, margins = c(5,10),
xlab = "specification variables", ylab = "Car Models",
main = "heatmap(<Mtcars data>, ..., scale = \"column\")")
utils::str(hv) # the two reordering index vectors
## no column dendrogram (nor reordering) at all:
heatmap(x, Colv = NA, col = cm.colors(256), scale = "column",
RowSideColors = rc, margins = c(5,10),
xlab = "specification variables", ylab = "Car Models",
main = "heatmap(<Mtcars data>, ..., scale = \"column\")")
## "no nothing"
heatmap(x, Rowv = NA, Colv = NA, scale = "column",
main = "heatmap(*, NA, NA) ~= image(t(x))")
round(Ca < cor(attitude), 2)
symnum(Ca) # simple graphic
heatmap(Ca, symm = TRUE, margins = c(6,6)) # with reorder()
heatmap(Ca, Rowv = FALSE, symm = TRUE, margins = c(6,6)) # _NO_ reorder()
## slightly artificial with color bar, without and with ordering:
cc < rainbow(nrow(Ca))
heatmap(Ca, Rowv = FALSE, symm = TRUE, RowSideColors = cc, ColSideColors = cc,
margins = c(6,6))
heatmap(Ca, symm = TRUE, RowSideColors = cc, ColSideColors = cc,
margins = c(6,6))
## For variable clustering, rather use distance based on cor():
symnum( cU < cor(USJudgeRatings) )
hU < heatmap(cU, Rowv = FALSE, symm = TRUE, col = topo.colors(16),
distfun = function(c) as.dist(1  c), keep.dendro = TRUE)
## The Correlation matrix with same reordering:
round(100 * cU[hU[[1]], hU[[2]]])
## The column dendrogram:
utils::str(hU$Colv)
Community examples
require(graphics); require(grDevices) 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", RowSihttps://www.rdocumentation.org/deColors = rc, ColSideColors = cc, margins = c(5,10), xlab = "specification variables", ylab = "Car Models", main = "heatmap(<Mtcars data>, ..., scale = \"column\")") utils::str(hv) # the two reordering index vectors ## no column dendrogram (nor reordering) at all: heatmap(x, Colv = NA, col = cm.colors(256), scale = "column", RowSideColors = rc, margins = c(5,10), xlab = "specification variables", ylab = "Car Models", main = "heatmap(<Mtcars data>, ..., scale = \"column\")") ## "no nothing" heatmap(x, Rowv = NA, Colv = NA, scale = "column", main = "heatmap(*, NA, NA) ~= image(t(x))") round(Ca < cor(attitude), 2) symnum(Ca) # simple graphic heatmap(Ca, symm = TRUE, margins = c(6,6)) # with reorder() heatmap(Ca, Rowv = FALSE, symm = TRUE, margins = c(6,6)) # _NO_ reorder() ## slightly artificial with color bar, without and with ordering: cc < rainbow(nrow(Ca)) heatmap(Ca, Rowv = FALSE, symm = TRUE, RowSideColors = cc, ColSideColors = cc, margins = c(6,6)) heatmap(Ca, symm = TRUE, RowSideColors = cc, ColSideColors = cc, margins = c(6,6)) ## For variable clustering, rather use distance based on cor(): symnum( cU < cor(USJudgeRatings) ) hU < heatmap(cU, Rowv = FALSE, symm = TRUE, col = topo.colors(16), distfun = function(c) as.dist(1  c), keep.dendro = TRUE) ## The Correlation matrix with same reordering: round(100 * cU[hU[[1]], hU[[2]]]) ## The column dendrogram: utils::str(hU$Colv)