Skip to contents

Plot heatmaps

Source: R/cHeatmap.R
cHeatmap.Rd

This is a wrapper of the ComplexHeatmap::Heatmap() with additional functions and more friendly interfaces for some common tasks in plotting heatmaps.

Usage

cHeatmap(
  mat1,
  NA.color = "grey",
  whiteValue = NA,
  colMap = c(green4 = NA, white = whiteValue, red = NA),
  intAsDiscreteCutoff = 6,
  legendPos = c("right", "left", "bottom", "top"),
  nRowCluster = NULL,
  nColmCluster = NULL,
  rowAnnoDf = NULL,
  colmAnnoDf = NULL,
  rowAnnoPara = list(na_col = NA.color),
  colmAnnoPara = list(na_col = NA.color),
  rowAnnoColMap = NULL,
  colmAnnoColMap = NULL,
  drawHeatmap = T,
  rmLegendOutliers = is.numeric(mat1),
  cellFun = NULL,
  annoCellFunList = NULL,
  cfMat = mat1,
  cellFontSize = 9,
  cellFontColor = "black",
  rowDraw = NULL,
  legendBreakDist = NULL,
  legendHeight = NULL,
  legendTicks = NULL,
  legendTickLabels = NULL,
  asGGplot = FALSE,
  ...
)

Arguments

mat1

A numeric or character matrix or data frame, required.

NA.color

character,'grey'; the color for missing values in mat1, rowAnnoDf, or colmAnnoDf. If missing values are present, a square of NA.color will be added to the legend.

whiteValue

Numeric, NULL; it is the value of the white or middle color in the legend if mat1 is numeric and colMap consists of three colors.

colMap

A vector, c("green4"=NA, "white"=whiteValue, "red"=NA); it defines the colors used in the heatmap and their mapping to values, and therefore should be supplied as a named vector.

  • For character mat1, colMap is a character vector, i.e. c('red'='a','pink'='b','yellow'='c') if the unique values in mat1 are a, b, and c.

  • For numeric mat1, colMap is a numeric vector, i.e. c('blue'= NA,'green'=5, 'red'=10)

    1. colMap can be supplied w/o names for convenience, i.e. c(-1, 0, 3); in this case, the length must be three and names are assumed to be c("green4", "white", "red")

    2. The first and last value of colMap are the lower and upper bounds of displayed values; values outside of that range will be considered as outliers.

    3. One or both of the first and last values of colMap can be supplied as NA; then outliers will be auto-computed if rmLegendOutliers is TRUE.

intAsDiscreteCutoff

integer, 6; if mat1 is an integer matrix and has < 6 unique values, the color mapping in the legend will be discrete.

legendPos

one of c("right", "left", "bottom", "top")

nRowCluster, nColmCluster

integer, NULL; number of colored clusters in row or column; different clusters will be in different colors. If this argument is set, it assumes cluster_rows and cluster_columns are TRUE; so do NOT explicitly set those two arguments again. To also split, i.e. columns, set column_split = nColmCluster.

rowAnnoDf, colmAnnoDf

matrix or data frame, NULL; annotation for row or column. The rows of the rowAnnoDf/colmAnnoDf should be of the same length and order of the row/column of mat1.

rowAnnoPara, colmAnnoPara

list, list(na_col = NA.color); passed to ComplexHeatmap::rowAnnotation() or ComplexHeatmap::columnAnnotation()

rowAnnoColMap, colmAnnoColMap

list, NULL; the color mappings for row and column annotations are handled automatically. Use this parameter to manually set the color mappings, names(list) is the names of each annotation. Each item of the list is a vector named by colors, similar to parameter colMap.

  • If an annotation is numeric, the vector is numeric, i.e. c("green4"= -1, "yellow"=0, "red"=5)

  • If an annotation is not numeric, the vector is character, i.e. c('red'='a','pink'='b','yellow'='c')

drawHeatmap

logical, TRUE; it uses ComplexHeatmap::draw() to merge all legends into one column and draw the final heatmap.

  • It should be set to TRUE to obtain the clustering orders, i.e. by column_order()

  • However, it should be FALSE if the returned heatmap from cHeatmap() will be concatenated with other heatmaps.

rmLegendOutliers

logical, is.numeric(mat1); if TRUE, only non-outliers are used in the color-value mappings; passed to setColMapAndLegend()

cellFun

NULL; it is used to display info for individual cells; text info can be formatted by cellFontSize and cellFontColor. here are different usages:

  • A function to determine where and what to display at certain cells; it takes a cell value as input and the returned value is to be displayed. for example:

    • cellFun = function(x){x}: display the value of each cell

    • cellFun = function(x){if(x > 10) x}: display the value of cells whose values are greater than 10

    • cellFun = function(x){if(x > 10) '?'}: display the '?' sign

    • cellFun = function(x){if(x > 10) list('rect',col='black',lwd=2)}: color the edges black and set line width as 2. Check the parameters of grid::gpar() for more controls.

  • A character vector or list:

    • cellFun = 'o': display the values of all the outliers in mat1 if any

    • cellFun = c('o','+'): display the '+' sign instead of the value at the outlier cells

    • cellFun=c('o',list('rect',col='red',lwd=2)): color the outlier cells with red edges

The 'o' and 'rect' are hard coded cases for usage convenience; for more complicated cell drawing, use the parameter cell_fun of ComplexHeatmap::Heatmap() directly.

annoCellFunList

list of functions to define the indices and content to display values of annotation, NULL; to use this, drawHeatmap must be TRUE; the returned value of each function can be the followings:

  • A vector, the actual values of the annotation are displayed

    • if the vector is 'o', the cells to display are the outliers

    • otherwise, the vector should be indices in the original rowAnnoDf or colmAnnoDf

  • A list of two vectors

    • the 1st vector is defined as above

    • the 2nd vector is a single string as the content to display for example, here the columns height and name are used as annotation:

  • annoCellFunList = list(height=\(x){ which(x>6)},name=\(x) {1:2})): display the heights greater than 6 and the first two names

  • annoCellFunList = list(height=\(x){'o'},name=\(x) {list(1:2,'x')})): display the outlier heights and the first two names as 'x'

cfMat

mat1; the matrix for the cells in cellFun; it should have the same dimension as mat1. It gives the option of using a different matrix for the evaluation of cellFun and display its results on top of the heatmap from mat1.

cellFontSize, cellFontColor

numeric, 9; character, "white"; format text displayed in heatmap cells.

rowDraw

list, NULL; it is used to plot across rows. The list should contain the following item:

  1. the function in the grid package to make the draw and its parameters; for examples:

    • list('grid.points',size = grid::unit(0.3, "char"),gp=grid::gpar(col='black')) ; see grid::grid.points() for details. For grid.point, it can also be simply coded as list('grid.points',size = 0.3,pch=1,col='black'); parameter col and followed items are for gpar().

    • list('grid.lines',gp=grid::gpar(col='black',lwd = 2)); see grid::grid.lines() for details. For grid.lines, it can also be simply coded as list('grid.lines',col='black',lwd = 2) parameter col and followed items are for gpar().

    • list( list('grid.points',size = 0.3,col='black'), list('grid.lines',col='black',lwd = 2) ) for multiple drawings

  2. a matrix containing the data to make the drawing, its number of columns

  3. an integer vector specifying the rows to make the drawing; if NULL, it means all the rows of mat1 and assumes nrow() == nrow(mat1) for the supplied matrix at #2

See the parameter layer_fun of ComplexHeatmap::Heatmap() for more complex drawing across a block of cells.

legendBreakDist

numeric vector, NULL; set the distance portion between two breaks in the legend and can be the following values:

  • NULL; the numeric distance among breaks

  • 1; equal distance among breaks

  • a numeric vector to represent the relative length of each section between two breaks; its length should be length(legendTicks) - 1;

legendHeight

numeric, NULL; height of the vertical legend in cm.

legendTicks

numeric, NULL; the legend tick; default is the unname(colMap) but can be any numeric vector whose range is within unname(colMap).

legendTickLabels

character, NULL; the label of legend tick; should be the same length as the legendTicks; use ” to skip a tick.

asGGplot

logical, FALSE; to output as ggplot object, drawHeatmap must be TRUE

...

passed to ComplexHeatmap::Heatmap()

Value

a ggplot object if asGGplot = TRUE, or a ComplexHeatmap::HeatmapList object if drawHeatmap = TRUE, or a ComplexHeatmap::Heatmap object otherwise.

Details

Here are the features:

  1. Automatic or manual exclusion of outliers in the color mapping so that the color scale of the heatmap and annotations is not dominated by outliers.

  2. The option to set the color-value mappings for the body and annotations of heatmaps.

  3. Automatic coloring of the dendrogram.

  4. Easy highlight or display of the values of certain cells in the body and annotations of the heatmap.

  5. Discrete color-value mapping for integer matrices containing few unique values.

  6. Clustering of the character matrix based on the orders of characters.

  7. Interface to plot across rows.

  8. Handling of edge cases:

    • Inf and -Inf values in input matrix cause errors in stats::dist() for clustering, they are reset as NA.

    • If missing values are present in the input matrix or row and column annotations, a legend for missing value is added.

    • Plot a heatmap of a data.frame with columns of different data types clustered by one of the columns.

Examples

# examples at https://blueskypie.github.io/cHeatmap/articles/cHeatmap-intro.html