# 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 or`NA`

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*when`x`

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`

or`Colv`

are not dendrograms. Defaults to`hclust`

. Should take as argument a result of`distfun`

and return an object to which`as.dendrogram`

can be applied.- reorderfun
`function(d, w)`

of dendrogram and weights for reordering the row and column dendrograms. The default uses`reorder.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**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.

- keep.dendro
logical indicating if the dendrogram(s) should be kept as part of the result (when

`Rowv`

and/or`Colv`

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 RColorBrewer package.

##### Value

Invisibly, a list with components

**r**ow index permutation vector as returned by
`order.dendrogram`

.

**c**olumn index permutation vector.

the row dendrogram; only if input `Rowv`

was not NA
and `keep.dendro`

is true.

the column dendrogram; only if input `Colv`

was not NA
and `keep.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)`

```
# NOT RUN {
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 re-ordering 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\")")
# }
# NOT RUN {
## "no nothing"
heatmap(x, Rowv = NA, Colv = NA, scale = "column",
main = "heatmap(*, NA, NA) ~= image(t(x))")
# }
# NOT RUN {
<!-- %% also want example using the `add.exp' argument! -->
# }
# NOT RUN {
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)
# }
```

*Documentation reproduced from package stats, version 3.5.2, License: Part of R 3.5.2*

### Community examples

**Glennlee**at Jan 20, 2017 stats v3.2.1

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 re-ordering 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)