labeledHeatmap: Produce a labeled heatmap plot

In WGCNA: Weighted Correlation Network Analysis

Produce a labeled heatmap plot

Description

Plots a heatmap plot with color legend, row and column annotation, and optional text within th heatmap.

Usage

labeledHeatmap(
  Matrix, 
  xLabels, yLabels = NULL, 
  xSymbols = NULL, ySymbols = NULL, 
  colorLabels = NULL, 
  xColorLabels = FALSE, yColorLabels = FALSE, 
  checkColorsValid = TRUE,
  invertColors = FALSE, 
  setStdMargins = TRUE, 
  xLabelsPosition = "bottom",
  xLabelsAngle = 45,
  xLabelsAdj = 1,
  yLabelsPosition = "left",
  xColorWidth = 2 * strheight("M"),
  yColorWidth = 2 * strwidth("M"), 
  xColorOffset = strheight("M")/3, 
  yColorOffset = strwidth("M")/3,
  colorMatrix = NULL,
  colors = NULL, 
  naColor = "grey",
  textMatrix = NULL, 
  cex.text = NULL, 
  textAdj = c(0.5, 0.5),
  cex.lab = NULL, 
  cex.lab.x = cex.lab,
  cex.lab.y = cex.lab,
  colors.lab.x = 1,
  colors.lab.y = 1,
  font.lab.x = 1,
  font.lab.y = 1,

  bg.lab.x = NULL,
  bg.lab.y = NULL,
  x.adj.lab.y = 1,

  plotLegend = TRUE, 
  keepLegendSpace = plotLegend,
  legendLabel = "",
  cex.legendLabel = 1,

  # Separator line specification                   
  verticalSeparator.x = NULL,
  verticalSeparator.col = 1,
  verticalSeparator.lty = 1,
  verticalSeparator.lwd = 1,
  verticalSeparator.ext = 0,
  verticalSeparator.interval = 0,

  horizontalSeparator.y = NULL,
  horizontalSeparator.col = 1,
  horizontalSeparator.lty = 1,
  horizontalSeparator.lwd = 1,
  horizontalSeparator.ext = 0,
  horizontalSeparator.interval = 0,
  # optional restrictions on which rows and columns to actually show
  showRows = NULL,
  showCols = NULL,
  ...)

Arguments

Matrix	numerical matrix to be plotted in the heatmap.
xLabels	labels for the columns. See Details.
yLabels	labels for the rows. See Details.
xSymbols	additional labels used when xLabels are interpreted as colors. See Details.
ySymbols	additional labels used when yLabels are interpreted as colors. See Details.
colorLabels	logical: should xLabels and yLabels be interpreted as colors? If given, overrides xColorLabels and yColorLabels below.
xColorLabels	logical: should xLabels be interpreted as colors?
yColorLabels	logical: should yLabels be interpreted as colors?
checkColorsValid	logical: should given colors be checked for validity against the output of colors() ? If this argument is FALSE, invalid color specification will trigger an error.
invertColors	logical: should the color order be inverted?
setStdMargins	logical: should standard margins be set before calling the plot function? Standard margins depend on colorLabels: they are wider for text labels and narrower for color labels. The defaults are static, that is the function does not attempt to guess the optimal margins.
xLabelsPosition	a character string specifying the position of labels for the columns. Recognized values are (unique abbreviations of) "top", "bottom".
xLabelsAngle	angle by which the column labels should be rotated.
xLabelsAdj	justification parameter for column labels. See par and the description of parameter "adj".
yLabelsPosition	a character string specifying the position of labels for the columns. Recognized values are (unique abbreviations of) "left", "right".
xColorWidth	width of the color labels for the x axis expressed in user corrdinates.
yColorWidth	width of the color labels for the y axis expressed in user coordinates.
xColorOffset	gap between the y axis and color labels, in user coordinates.
yColorOffset	gap between the x axis and color labels, in user coordinates.
colorMatrix	optional explicit specification for the color of the heatmap cells. If given, overrides values specified in colors and naColor.
colors	color pallette to be used in the heatmap. Defaults to heat.colors. Only used if colorMatrix is not given.
naColor	color to be used for encoding missing data. Only used if colorMatrix is not used.
textMatrix	optional text entries for each cell. Either a matrix of the same dimensions as Matrix or a vector of the same length as the number of entries in Matrix.
cex.text	character expansion factor for textMatrix.
textAdj	Adjustment for the entries in the text matrix. See the adj argument to text.
cex.lab	character expansion factor for text labels labeling the axes.
cex.lab.x	character expansion factor for text labels labeling the x axis. Overrides cex.lab above.
cex.lab.y	character expansion factor for text labels labeling the y axis. Overrides cex.lab above.
colors.lab.x	colors for character labels or symbols along x axis.
colors.lab.y	colors for character labels or symbols along y axis.
font.lab.x	integer specifying font for labels or symbols along x axis. See text.
font.lab.y	integer specifying font for labels or symbols along y axis. See text.
bg.lab.x	background color for the margin along the x axis.
bg.lab.y	background color for the margin along the y axs.
x.adj.lab.y	Justification of labels for the y axis along the x direction. A value of 0 produces left-justified text, 0.5 (the default) centered text and 1 right-justified text.
plotLegend	logical: should a color legend be plotted?
keepLegendSpace	logical: if the color legend is not drawn, should the space be left empty (TRUE), or should the heatmap fill the space (FALSE)?
legendLabel	character string to be shown next to the label analogous to an axis label.
cex.legendLabel	character expansion factor for the legend label.
verticalSeparator.x	indices of columns in input Matrix after which separator lines (vertical lines between columns) should be drawn. NULL means no lines will be drawn.
verticalSeparator.col	color(s) of the vertical separator lines. Recycled if need be.
verticalSeparator.lty	line type of the vertical separator lines. Recycled if need be.
verticalSeparator.lwd	line width of the vertical separator lines. Recycled if need be.
verticalSeparator.ext	number giving the extension of the separator line into the margin as a fraction of the margin width. 0 means no extension, 1 means extend all the way through the margin.
verticalSeparator.interval	number giving the interval for vertical separators. If larger than zero, vertical separators will be drawn after every verticalSeparator.interval of displayed columns. Used only when length of verticalSeparator.x is zero.
horizontalSeparator.y	indices of columns in input Matrix after which separator lines (horizontal lines between columns) should be drawn. NULL means no lines will be drawn.
horizontalSeparator.col	color(s) of the horizontal separator lines. Recycled if need be.
horizontalSeparator.lty	line type of the horizontal separator lines. Recycled if need be.
horizontalSeparator.lwd	line width of the horizontal separator lines. Recycled if need be.
horizontalSeparator.ext	number giving the extension of the separator line into the margin as a fraction of the margin width. 0 means no extension, 1 means extend all the way through the margin.
horizontalSeparator.interval	number giving the interval for horizontal separators. If larger than zero, horizontal separators will be drawn after every horizontalSeparator.interval of displayed rows. Used only when length of horizontalSeparator.y is zero.
showRows	A numeric vector giving the indices of rows that are actually to be shown. Defaults to all rows.
showCols	A numeric vector giving the indices of columns that are actually to be shown. Defaults to all columns.
...	other arguments to function heatmap.

Details

The function basically plots a standard heatmap plot of the given Matrix and embellishes it with row and column labels and/or with text within the heatmap entries. Row and column labels can be either character strings or color squares, or both.

To get simple text labels, use colorLabels=FALSE and pass the desired row and column labels in yLabels and xLabels, respectively.

To label rows and columns by color squares, use colorLabels=TRUE; yLabels and xLabels are then expected to represent valid colors. For reasons of compatibility with other functions, each entry in yLabels and xLabels is expected to consist of a color designation preceded by 2 characters: an example would be MEturquoise. The first two characters can be arbitrary, they are stripped. Any labels that do not represent valid colors will be considered text labels and printed in full, allowing the user to mix text and color labels.

It is also possible to label rows and columns by both color squares and additional text annotation. To achieve this, use the above technique to get color labels and, additionally, pass the desired text annotation in the xSymbols and ySymbols arguments.

Value

None.

Author(s)

Peter Langfelder

See Also

heatmap, colors

Examples

# This example illustrates 4 main ways of annotating columns and rows of a heatmap.
# Copy and paste the whole example into an R session with an interactive plot window;
# alternatively, you may replace the command sizeGrWindow below by opening 
# another graphical device such as pdf.

# Generate a matrix to be plotted

nCol = 8; nRow = 7;
mat = matrix(runif(nCol*nRow, min = -1, max = 1), nRow, nCol);

rowColors = standardColors(nRow);
colColors = standardColors(nRow + nCol)[(nRow+1):(nRow + nCol)];

rowColors;
colColors;

sizeGrWindow(9,7)
par(mfrow = c(2,2))
par(mar = c(4, 5, 4, 6));

# Label rows and columns by text:

labeledHeatmap(mat, xLabels = colColors, yLabels = rowColors, 
               colors = greenWhiteRed(50),
               setStdMargins = FALSE, 
               textMatrix = signif(mat, 2),
               main = "Text-labeled heatmap");

# Label rows and columns by colors:

rowLabels = paste("ME", rowColors, sep="");
colLabels = paste("ME", colColors, sep="");

labeledHeatmap(mat, xLabels = colLabels, yLabels = rowLabels,
               colorLabels = TRUE,
               colors = greenWhiteRed(50),
               setStdMargins = FALSE,
               textMatrix = signif(mat, 2),
               main = "Color-labeled heatmap");

# Mix text and color labels:

rowLabels[3] = "Row 3";
colLabels[1] = "Column 1";

labeledHeatmap(mat, xLabels = colLabels, yLabels = rowLabels,
               colorLabels = TRUE,
               colors = greenWhiteRed(50),
               setStdMargins = FALSE,
               textMatrix = signif(mat, 2), 
               main = "Mix-labeled heatmap");

# Color labels and additional text labels

rowLabels = paste("ME", rowColors, sep="");
colLabels = paste("ME", colColors, sep="");

extraRowLabels = paste("Row", c(1:nRow));
extraColLabels = paste("Column", c(1:nCol));

# Extend margins to fit all labels
par(mar = c(6, 6, 4, 6));
labeledHeatmap(mat, xLabels = colLabels, yLabels = rowLabels,
               xSymbols = extraColLabels,
               ySymbols = extraRowLabels,
               colorLabels = TRUE,
               colors = greenWhiteRed(50),
               setStdMargins = FALSE,
               textMatrix = signif(mat, 2),
               main = "Text- + color-labeled heatmap");

WGCNA documentation built on Sept. 18, 2024, 5:08 p.m.