heatmap.2 {gplots}  R Documentation 
A heat map is a false color image (basically
image(t(x))
) with a dendrogram added to the left side
and/or 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.
This heatmap provides a number of extensions to the standard R
heatmap
function.
heatmap.2 (x, # dendrogram control Rowv = TRUE, Colv=if(symm)"Rowv" else TRUE, distfun = dist, hclustfun = hclust, dendrogram = c("both","row","column","none"), symm = FALSE, # data scaling scale = c("none","row", "column"), na.rm=TRUE, # image plot revC = identical(Colv, "Rowv"), add.expr, # mapping data to colors breaks, symbreaks=min(x < 0, na.rm=TRUE)  scale!="none", # colors col="heat.colors", # block sepration colsep, rowsep, sepcolor="white", sepwidth=c(0.05,0.05), # cell labeling cellnote, notecex=1.0, notecol="cyan", na.color=par("bg"), # level trace trace=c("column","row","both","none"), tracecol="cyan", hline=median(breaks), vline=median(breaks), linecol=tracecol, # Row/Column Labeling margins = c(5, 5), ColSideColors, RowSideColors, cexRow = 0.2 + 1/log10(nr), cexCol = 0.2 + 1/log10(nc), labRow = NULL, labCol = NULL, srtRow = NULL, srtCol = NULL, adjRow = c(0,NA), adjCol = c(NA,0), offsetRow = 0.5, offsetCol = 0.5, # color key + density info key = TRUE, keysize = 1.5, density.info=c("histogram","density","none"), denscol=tracecol, symkey = min(x < 0, na.rm=TRUE)  symbreaks, densadj = 0.25, # plot labels main = NULL, xlab = NULL, ylab = NULL, # plot layout lmat = NULL, lhei = NULL, lwid = NULL, # extras ... )
x 
numeric matrix of the values to be plotted. 
Rowv 
determines if and how the row dendrogram should be
reordered. By default, it is TRUE, which implies dendrogram is
computed and reordered based on row means. If NULL or FALSE, then no
dendrogram is computed and no reordering is done. If a

Colv 
determines if and how the column dendrogram should be
reordered. Has the options as the 
distfun 
function used to compute the distance (dissimilarity)
between both rows and columns. Defaults to 
hclustfun 
function used to compute the hierarchical clustering
when 
dendrogram 
character string indicating whether to draw 'none', 'row', 'column' or 'both' dendrograms. Defaults to 'both'. However, if Rowv (or Colv) is FALSE or NULL and dendrogram is 'both', then a warning is issued and Rowv (or Colv) arguments are honoured. 
symm 
logical indicating if 
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 
na.rm 
logical indicating whether 
revC 
logical indicating if the column order should be

add.expr 
expression that will be evaluated after the call to

breaks 
(optional) Either a numeric vector indicating the
splitting points for binning 
symbreaks 
Boolean indicating whether breaks should be
made symmetric about 0. Defaults to 
col 
colors used for the image. Defaults to heat colors
( 
colsep, rowsep, sepcolor 
(optional) vector of integers indicating
which columns or rows should be separated from the preceding columns
or rows by a narrow space of color 
sepwidth 
(optional) Vector of length 2 giving the width (colsep) or height (rowsep) the separator box
drawn by colsep and rowsep as a function of the width (colsep) or
height (rowsep) of a cell. Defaults to 
cellnote 
(optional) matrix of character strings which will be placed within each color cell, e.g. pvalue symbols. 
notecex 
(optional) numeric scaling factor for 
notecol 
(optional) character string specifying the color for

na.color 
Color to use for missing value ( 
trace 
character string indicating whether a solid "trace" line should be drawn across 'row's or down 'column's, 'both' or 'none'. The distance of the line from the center of each colorcell is proportional to the size of the measurement. Defaults to 'column'. 
tracecol 
character string giving the color for "trace" line. Defaults to "cyan". 
hline, vline, linecol 
Vector of values within cells where a
horizontal or vertical dotted line should be drawn. The color of
the line is controlled by 
margins 
numeric vector of length 2 containing the margins
(see 
ColSideColors 
(optional) character vector of length 
RowSideColors 
(optional) character vector of length 
cexRow, cexCol 
positive numbers, used as 
labRow, labCol 
character vectors with row and column labels to
use; these default to 
srtRow, srtCol 
angle of row/column labels, in degrees from horizontal 
adjRow, adjCol 
2element vector giving the (leftright, topbottom) justification of row/column labels (relative to the text orientation). 
offsetRow, offsetCol 
Number of characterwidth spaces to place between row/column labels and the edge of the plotting region. 
key 
logical indicating whether a colorkey should be shown. 
keysize 
numeric value indicating the size of the key 
density.info 
character string indicating whether to superimpose a 'histogram', a 'density' plot, or no plot ('none') on the colorkey. 
denscol 
character string giving the color for the density
display specified by 
symkey 
Boolean indicating whether the color key should be
made symmetric about 0. Defaults to 
densadj 
Numeric scaling value for tuning the kernel width when
a density plot is drawn on the color key. (See the 
main, xlab, ylab 
main, x and yaxis titles; defaults to none. 
lmat, lhei, lwid 
visual layout: position matrix, column height, column width. See below for details 
... 
additional arguments passed on to 
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.
If 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 range from red to white (heat.colors
) and
are not pretty. Consider using enhancements such
as the RColorBrewer package,
http://cran.rproject.org/src/contrib/PACKAGES.html#RColorBrewer
to select better colors.
By default four components will be displayed in the plot. At the top
left is the color key, top right is the column dendogram, bottom left
is the row dendogram, bottom right is the image plot. When
RowSideColor or ColSideColor are provided, an additional row or column
is inserted in the appropriate location. This layout can be
overriden by specifiying appropriate values for lmat
,
lwid
, and lhei
. lmat
controls the relative
postition of each element, while lwid
controls the column
width, and lhei
controls the row height. See the help page for
layout
for details on how to use these
arguments.
Invisibly, a list with components
rowInd 
row index permutation vector as returned by

colInd 
column index permutation vector. 
call 
the matched call 
rowMeans, rowSDs 
mean and standard deviation of each row: only
present if 
colMeans, colSDs 
mean and standard deviation of each column: only
present if 
carpet 
reordered and scaled 'x' values used generate the main 'carpet' 
rowDendrogram 
row dendrogram, if present 
colDendrogram 
column dendrogram, if present 
breaks 
values used for color break points 
col 
colors used 
vline 
centerline value used for column trace, present only if

hline 
centerline value used for row trace, present only if

colorTable 
A threecolumn data frame providing the lower and upper bound and color for each bin 
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.2()
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.
Andy Liaw, original; R. Gentleman, M. Maechler, W. Huber, G. Warnes, revisions.
hclust
library(gplots) data(mtcars) x < as.matrix(mtcars) rc < rainbow(nrow(x), start=0, end=.3) cc < rainbow(ncol(x), start=0, end=.3) ## ## demonstrate the effect of row and column dendogram options ## heatmap.2(x) ## default  dendrogram plotted and reordering done. heatmap.2(x, dendrogram="none") ## no dendrogram plotted, but reordering done. heatmap.2(x, dendrogram="row") ## row dendrogram plotted and row reordering done. heatmap.2(x, dendrogram="col") ## col dendrogram plotted and col reordering done. heatmap.2(x, keysize=2) ## default  dendrogram plotted and reordering done. heatmap.2(x, Rowv=FALSE, dendrogram="both") ## generate warning! heatmap.2(x, Rowv=NULL, dendrogram="both") ## generate warning! heatmap.2(x, Colv=FALSE, dendrogram="both") ## generate warning! ## Show effect of row and column label rotation heatmap.2(x, srtCol=NULL) heatmap.2(x, srtCol=0, adjCol = c(0.5,1) ) heatmap.2(x, srtCol=45, adjCol = c(1,1) ) heatmap.2(x, srtCol=135, adjCol = c(1,0) ) heatmap.2(x, srtCol=180, adjCol = c(0.5,0) ) heatmap.2(x, srtCol=225, adjCol = c(0,0) ) ## not very useful heatmap.2(x, srtCol=270, adjCol = c(0,0.5) ) heatmap.2(x, srtCol=315, adjCol = c(0,1) ) heatmap.2(x, srtCol=360, adjCol = c(0.5,1) ) heatmap.2(x, srtRow=45, adjRow=c(0, 1) ) heatmap.2(x, srtRow=45, adjRow=c(0, 1), srtCol=45, adjCol=c(1,1) ) heatmap.2(x, srtRow=45, adjRow=c(0, 1), srtCol=270, adjCol=c(0,0.5) ) ## Show effect of offsetRow/offsetCol (only works when srtRow/srtCol is ## not also present) heatmap.2(x, offsetRow=0, offsetCol=0) heatmap.2(x, offsetRow=1, offsetCol=1) heatmap.2(x, offsetRow=2, offsetCol=2) heatmap.2(x, offsetRow=1, offsetCol=1) heatmap.2(x, srtRow=0, srtCol=90, offsetRow=0, offsetCol=0) heatmap.2(x, srtRow=0, srtCol=90, offsetRow=1, offsetCol=1) heatmap.2(x, srtRow=0, srtCol=90, offsetRow=2, offsetCol=2) heatmap.2(x, srtRow=0, srtCol=90, offsetRow=1, offsetCol=1) ## ## Show effect of zscore scaling within columns, bluered color scale ## hv < heatmap.2(x, col=bluered, scale="column", tracecol="#303030") ### ## Look at the return values ### names(hv) ## Show the mapping of zscore values to color bins hv$colorTable ## Extract the range associated with white hv$colorTable[hv$colorTable[,"color"]=="#FFFFFF",] ## Determine the original data values that map to white whiteBin < unlist(hv$colorTable[hv$colorTable[,"color"]=="#FFFFFF",1:2]) rbind(whiteBin[1] * hv$colSDs + hv$colMeans, whiteBin[2] * hv$colSDs + hv$colMeans ) ## ## A more decorative heatmap, with zscore scaling along columns ## hv < heatmap.2(x, col=cm.colors(255), scale="column", RowSideColors=rc, ColSideColors=cc, margin=c(5, 10), xlab="specification variables", ylab= "Car Models", main="heatmap(<Mtcars data>, ..., scale=\"column\")", tracecol="green", density="density") ## Note that the breakpoints are now symmetric about 0 data(attitude) round(Ca < cor(attitude), 2) symnum(Ca) # simple graphic # with reorder heatmap.2(Ca, symm=TRUE, margin=c(6, 6), trace="none" ) # without reorder heatmap.2(Ca, Rowv=FALSE, symm=TRUE, margin=c(6, 6), trace="none" ) ## Place the color key below the image plot heatmap.2(x, lmat=rbind( c(0, 3), c(2,1), c(0,4) ), lhei=c(1.5, 4, 2 ) ) ## Place the color key to the top right of the image plot heatmap.2(x, lmat=rbind( c(0, 3, 4), c(2,1,0 ) ), lwid=c(1.5, 4, 2 ) ) ## For variable clustering, rather use distance based on cor(): data(USJudgeRatings) symnum( cU < cor(USJudgeRatings) ) hU < heatmap.2(cU, Rowv=FALSE, symm=TRUE, col=topo.colors(16), distfun=function(c) as.dist(1  c), trace="none") ## The Correlation matrix with same reordering: hM < format(round(cU, 2)) hM # now with the correlation matrix on the plot itself heatmap.2(cU, Rowv=FALSE, symm=TRUE, col=rev(heat.colors(16)), distfun=function(c) as.dist(1  c), trace="none", cellnote=hM) ## genechip data examples ## Not run: library(affy) data(SpikeIn) pms < SpikeIn@pm # just the data, scaled across rows heatmap.2(pms, col=rev(heat.colors(16)), main="SpikeIn@pm", xlab="Relative Concentration", ylab="Probeset", scale="row") # fold change vs "12.50" sample data < pms / pms[, "12.50"] data < ifelse(data>1, data, 1/data) heatmap.2(data, breaks=16, col=redgreen, tracecol="blue", main="SpikeIn@pm Fold Changes\nrelative to 12.50 sample", xlab="Relative Concentration", ylab="Probeset") ## End(Not run)