heatmap.3: Plot TROM scores in a heatmap.
In TROM: Transcriptome Overlap Measure

Description Usage Arguments Value Author(s) References See Also Examples

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 -log10 (transformed Bonferroni corrected p-values) saturated at a default value of 6. The TROM scores are calculated from function ws.trom() or bs.trom().

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, ...)

`x`	numeric matrix of the TROM scores (-log10 transformed Bonferroni corrected p-values) to be plotted.
`max_score`	numeric value specifying the saturated value of TROM scores, i.e., -log10 (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/log10(nr) and 0.2 + 1/log10(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.

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

Jingyi Jessica Li, Wei Vivian Li

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

image, heatmap

## 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()
## End(Not run)