heatmap.3: Plot TROM scores in a heatmap.

Description

heatmap.3 plots the TROM scores obtained from mapping different biological samples. Larger TROM scores are shown in darker colors, corresponding to a scale showing -log\(_{10}\) (transformed Bonferroni corrected p-values) saturated at a default value of 6. The TROM scores are calculated from function ws.trom() or bs.trom().

Usage

heatmap.3(x, max_score=6, Rowv = TRUE, 
          Colv = if (symm) "Rowv" else TRUE, 
          distfun = dist, hclustfun = hclust, 
          dendrogram = c("both", "row", "column", "none"),       
          symm = FALSE, scale = c("none", "row", "column"), 
          na.rm = TRUE, revC = identical(Colv,"Rowv"), 
          add.expr, breaks, 
          symbreaks = min(x < 0, na.rm = TRUE) || scale != "none", 
          col = "heat.colors", colsep, rowsep, sepcolor = "white", 
          sepwidth = c(0.05, 0.05), cellnote, 
          notecex = 1, notecol = "cyan", 
          na.color = par("bg"), 
          trace = c("none"), 
          tracecol = "cyan", hline = median(breaks), 
          vline = median(breaks), linecol = tracecol, 
          margins = c(5, 5), ColSideColors, RowSideColors, 
          cexRow = 0.2 + 1/log10(nr), cexCol = 0.2 + 1/log10(nc), 
          labRow = NULL, labCol = NULL, key = TRUE, keysize = 1.5, 
          density.info = c("histogram", "density", "none"), 
          denscol = tracecol, 
          symkey = min(x < 0, na.rm = TRUE) || symbreaks, densadj = 0.25, 
          main = NULL, xlab = NULL, ylab = NULL, lmat = NULL, 
          lhei = NULL, lwid = NULL, 
          leftMargin = 7, bottomMargin = 7, reverse = FALSE, ...)

Arguments

numeric matrix of the TROM scores (-log\(_{10}\) transformed Bonferroni corrected p-values) to be plotted.

max_score

numeric value specifying the saturated value of TROM scores, i.e., -log\(_{10}\) (transformed Bonferroni corrected p-values). The TROM scores are saturated at max_score: TROM score=min(TROM score, max_score). The defualt value of max_score is 6.

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.

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.

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 honored.

symm

logical indicating if x should be treated symmetrically; can only be true when x is a square matrix.

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 "none".

na.rm

logical indicating whether NA's should be removed.

revC

logical indicating if the column order should be reversed for plotting, such that e.g., for the symmetric case, the symmetry axis is from lower left to upper right.

add.expr

expression that will be evaluated after the call to image. Can be used to add components to the plot, eg., add.expr=abline(...)

breaks

(optional) either a numeric vector indicating the splitting points for binning x into colors, or a integer number of break points to be used, in which case the break points will be spaced equally between min(x) and max(x).

symbreaks

Boolean indicating whether breaks should be made symmetric about 0. Defaults to TRUE if the data includes negative values, and to FALSE otherwise.

col

colors used for the image. Defaults to heat colors (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 box of the color sepcolor.

sepwidth

(optional) vector of length 2 giving the line width of the 2 vertical lines and the line width of the 2 horizontal lines of the separation box to be drawn, as a proportion of the width or height of a cell. Defaults to c(0.05, 0.05)

cellnote

(optional) matrix of character strings which will be placed inside some cells, e.g. p-value symbols.

notecex

(optional) numeric scaling factor for cellnote. Defaults to 1.

notecol

(optional) character string specifying the color for cellnote. Defaults to "cyan".

na.color

color to use for missing value (NA). Defaults to the background color.

trace

character string indicating whether a solid "trace" line should be drawn along "row"s or down "column"s, "both" or "none". The distance of the line from the center of each colored cell 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

(optional) vector of values within cells where a horizontal or vertical dotted line should be drawn. The color of the line is controlled by linecol. Horizontal lines are only plotted if trace is 'row' or 'both'. Vertical lines are only drawn if trace is "column" or "both". hline and vline default to the median of the breaks, linecol defaults to the value of tracecol.

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. Defaults to 0.2 + 1/log\(_{10}\)(nr) and 0.2 + 1/log\(_{10}\)(ncol), respectively.

labRow, labCol

character vectors with row and column labels to use. Defaults to rownames(x) and colnames(x), respectively.

key

logical indicating whether a color-key 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 color-key.

denscol

character string giving the color for the density display specified by density.info, defaults to the same value as tracecol.

symkey

Boolean indicating whether the color key should be made symmetric about 0. Defaults to TRUE if the data includes negative values, and to 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 for the density function for details.) Defaults to 0.25.

main, xlab, ylab

main, x- and y-axis titles; defaults to "".

lmat, lhei, lwid

visual layout: position matrix, column height, column width.

leftMargin, bottomMargin

sets the left and bottom margins respectively of the plot region.

reverse

Boolean indicating whether to reverse the rows of x.

…

additional arguments passed on to image.

Value

Invisibly, a list with components

rowInd

row index permutation vector as returned by order.dendrogram.

colInd

column index permutation vector as returned by order.dendrogram.

call

the matched call

carpet

reordered and scaled 'x' values used to generate the main 'carpet'

breaks

values used for break points in the color key

col

a character vector giving all the color IDs used in the heatmap

colorTable

A three-column data frame providing the lower and upper bounds and a color for each bin

References

Li WV, Chen Y and Li JJ (2016). TROM: A Testing-Based Method for Finding Transcriptomic Similarity of Biological Samples. Statistics in Biosciences. DOI: 10.1007/s12561-016-9163-y

Li JJ, Huang H, Bickel PJ, & Brenner SE (2014). Comparison of D. melanogaster and C. elegans developmental stages, tissues, and cells by modENCODE RNA-seq data. Genome Research, 24(7), 1086-1101.

https://gist.github.com/nachocab/3853004

Examples

Run this code

# NOT RUN {
## using TROM to map developmental stages of D. melanogaster 

## dm_gene_expr.rda can be downloaded and unzipped from
## http://www.stat.ucla.edu/~jingyi.li/packages/TROM/TROM_Rdata.zip.

# }
# NOT RUN {
load("dm_gene_expr.rda")
dm_trom <- ws.trom(sp_gene_expr = dm_gene_expr, z_thre = 1.5, 
                   provide = FALSE)
                     
## Draw heatmap without dendrogram
pdf("D. melanogaster Stage Mapping (without dendrogram).pdf", width = 10, height =8)
heatmap.3(   dm_trom,
             Rowv = NULL,
             Colv = NULL,
             dendrogram = c("none"),
             distfun = dist,
             hclustfun = hclust,
             xlab = "",
             ylab = "",
             main = "D. melanogaster Stage Mapping",
             key = TRUE,
             keysize = 1,
             trace = "none",
             density.info = c("none"),
             col = terrain.colors(120)
  )
dev.off()

## Draw heatmap with dendrogram
pdf("D. melanogaster Stage Mapping (with dendrogram).pdf", width = 10, height= 8)
heatmap.3(   dm_trom,
             Rowv = TRUE,
             Colv = TRUE,
             dendrogram = c("row"),
             distfun = dist,
             hclustfun = hclust,
             xlab = "",
             ylab = "",
             main = "D. melanogaster Stage Mapping",
             key = TRUE,
             keysize = 1,
             trace = "none",
             density.info = c("none"),
             col = terrain.colors(120),
  )
dev.off()
# }
# NOT RUN {
# }