heatmap.3: Enhanced heat map

In raredd/rawr: rawr miscellaneous

Enhanced heat map

Description

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.

Some improvements in this version over heatmap or heatmap.2 include better defaults; more control of the layout, spacing, and margins; built-in 1-correlation distances; automatic color interpolation used in the heat map; optional multi-layered vertical and horizontal color bars; a smoother interpolation in the color key; and other improvements.

Usage

heatmap.3(
  x,
  Rowv = TRUE,
  Colv = if (symm) "Rowv" else TRUE,
  distfun = dist,
  hclustfun = hclust,
  symm = FALSE,
  scale = c("none", "row", "column"),
  na.rm = TRUE,
  revC = identical(Colv, "Rowv"),
  add.expr = NULL,
  breaks = NULL,
  symbreaks = max(x < 0, na.rm = TRUE) || scale != "none",
  cols = c("blue", "white", "red"),
  colsep = NULL,
  rowsep = NULL,
  sepcolor = par("bg"),
  sepwidth = c(1, 1),
  cellnote = NULL,
  notecex = 1,
  notecol = "cyan",
  na.color = par("bg"),
  trace = c("none", "column", "row", "both"),
  tracecol = "cyan",
  hline = median(breaks),
  vline = median(breaks),
  linecol = tracecol,
  margins = c(5, 5),
  dmargins = c(5, 5),
  ColSideColors = NULL,
  RowSideColors = NULL,
  ColSideColorsSize = 1,
  RowSideColorsSize = 1,
  side.height.fraction = 0.3,
  labRow = NULL,
  labCol = NULL,
  labRowCol = NULL,
  labColCol = NULL,
  cexRow = 0.2 + 1/log10(nr),
  cexCol = 0.2 + 1/log10(nc),
  key = TRUE,
  key.cex = 1.5,
  key.title = if (density.info %in% c("density", "histogram")) NULL else "Color Key",
  key.sub = NULL,
  density.info = c("none", "histogram", "density"),
  denscol = tracecol,
  symkey = max(x < 0, na.rm = TRUE) || symbreaks,
  densadj = 0.25,
  main = NULL,
  xlab = NULL,
  ylab = NULL,
  lmat = NULL,
  lhei = NULL,
  lwid = NULL,
  ...
)

Arguments

x	a numeric matrix of the values to be plotted
Rowv, Colv	logical or a dendrogram controlling the order and dendrogram along the rows and columns, respectively; for other options, see heatmap
distfun	a function used to compute the distance (dissimilarity) between both rows and columns (default is dist with Euclidean distance); alternatively, any of the methods can be passed as a character string; "spearman" or "pearson" may also be used which will calculate the distance as 1 - cor(x)
hclustfun	a function used to compute the hierarchical clustering when Rowv or Colv are not dendrograms; default is hclust; should take as argument a result of distfun and return an object to which as.dendrogram can be applied
symm	logical; if TRUE and x is a square matrix, x is treated symmetrically
scale	character indicating if x should be centered and scaled in either the row or column direction or neither; default is none
na.rm	logical; if TRUE, NAs are removed before calculating dendrogram weights; see reorder.dendrogram
revC	logical; if TRUE, the column order is reversed for plotting, e.g., for the symmetric case, the symmetry axis is as usual
add.expr	an expression evaluated after the call to image, useful for adding components to the plot
breaks	(optional) either a numeric vector indicating the splitting points for binning x into colors, or an integer number of break points to be used; for the latter, the break points will be spaced equally between min(x) and max(x)
symbreaks	logical; if TRUE, breaks are made symmetric about 0; default is TRUE if x contains negative values and FALSE otherwise
cols	a vector of character strings of two or more colors used for interpolation and passed to image; alternatively a function such as heat.colors taking an integer argument and returning a vector of colors
colsep, rowsep, sepcolor, sepwidth	(optional) vector of integers indicating which columns or rows should be separated from the preceding columns or rows by a narrow space of sepcolor; widths of space between is given by sepwidth
cellnote	(optional) a matrix having the same dimensions as x with text to be plotted in each cell
notecex, notecol	size and color for cellnote
na.color	color used for NA values; defaults to background color par('bg')
trace	character string indicating whether a solid "trace" line should be drawn across rows or down columns; the distance of the line from the center of each color-cell is proportional to the size of the measurement; one of "row", "column", "both", or "none" (default)
tracecol	color for trace line
hline, vline, linecol	a vector of values within cells where a horizontal or vertical dotted line should be drawn; the color of the line is controlled by linecol (default is tracecol) horizontal lines are only plotted if trace is "row" or "both"; vertical lines are only drawn if trace "column" or "both"; both hline and vline default to the median of the breaks
margins	numeric vector of length 2 controlling the margins for column and row names, respectively
dmargins	numeric vector of length 2 controlling the margins for column and row dendrograms, respectively; useful for "squishing"
ColSideColors, RowSideColors	(optional) character vector or matrix with color names for horizontal or vertical side bars useful for annotating columns and/or rows of x
ColSideColorsSize, RowSideColorsSize	numeric value controlling the sizes of the horizontal and vertical side bars, respectively
side.height.fraction	scaling factor for height and width of bars
labRow, labCol	row and column labels; defaults to row and column names of x; FALSE suppresses labels
labRowCol, labColCol	(optional) vectors of colors for row and column labels, recycled as needed
cexRow, cexCol	size for row and column labels
key	logical; if TRUE, a color key is drawn
key.cex	numeric value controlling the size of the color key
key.title, key.sub	main and sub titles for the color key
density.info	character string indicating whether to supermipose a "histogram" or a "density" plot on the color key; default is "none"
denscol	color for density.info; default is tracecol
symkey	logical; if TRUE, color key will be symmetric about 0; default is TRUE if x contains negative values and FALSE otherwise
densadj	numeric scaling value for tuning the kernel width when a density plot is drawn on the color key; see the adjust parameter in density; default is 0.25
main, xlab, ylab	main, x-, and y-axis labels
lmat, lhei, lwid	(optional) arguments for controlling layout heights and widths, passed to layout
...	additional arguments passed to image or further to plot

See Also

heatmap; heatmap.2; image; dendrogram; dist; hclust

Examples

x <- scale(as.matrix(mtcars))

heatmap.3(x)
heatmap.3(x, cols = 'heat.colors')
heatmap.3(x, cols = c('blue4', 'grey95', 'tomato'))

heatmap.3(x, distfun = dist)        ## default ('euclidean')
heatmap.3(x, distfun = 'euclidean') ## passed to dist
heatmap.3(x, distfun = 'manhattan') ## same
heatmap.3(x, distfun = 'spearman')  ## calculated 1 - cor
heatmap.3(x, distfun = 'pearson')   ## same


## example from ?stats::heatmap
x <- as.matrix(mtcars)
rc <- rainbow(nrow(x), start = 0, end = .3)
cc <- rainbow(ncol(x), start = 0, end = .3)

hm <- heatmap.3(
  x, cols = cm.colors(256), scale = 'column',
  RowSideColors = rc, ColSideColors = cc, margins = c(5, 10)
)
str(hm) ## the two re-ordering index vectors


## multiple variables for row and/or column colors
rc <- cbind(gear = x[, 'gear'], am = x[, 'am'], vs = x[, 'vs'])
rc[] <- palette()[rc + 2L]

cc <- rbind(var1 = nchar(colnames(x)), var2 = nchar(sort(colnames(x))))
cc[] <- palette()[cc]

hm <- heatmap.3(
  x, scale = 'column',
  distfun = 'spearman', hclustfun = 'ward.D2',
  RowSideColors = rc, ColSideColors = cc,
  margins = c(5, 10), labRowCol = rc[, 3], labColCol = cc[1, ],
  colsep = c(2, 6), rowsep = c(9, 14, 21), sepwidth = c(5, 2)
)


## layout control
hm$layout

heatmap.3(
  ## same as above
  x, scale = 'column',
  distfun = 'spearman', hclustfun = 'ward.D2',
  RowSideColors = rc, ColSideColors = cc,
  
  ## less "squish" of dendrograms
  dmargins = c(2, 2),
  
  ## more room for heat map in layout
  key = FALSE, margins = c(3, 8),
  
  ## fine control over layout heights and widths
  lhei = c(7, 2, 30),
  lwid = c(5, 1, 30),
  
  cellnote = x
)

raredd/rawr documentation built on March 4, 2024, 1:36 a.m.