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 = list(),
colmAnnoColMap = list(),
drawHeatmap = T,
resetOutliers = is.numeric(mat1),
clusterUsingResetValues = FALSE,
cellFun = NULL,
cfMat = mat1,
cellFontSize = 9,
cellFontColor = "black",
rowDraw = NULL,
legendBreakDist = NULL,
legendHeight = NULL,
legendTicks = NULL,
legendTickLabels = NULL,
...
)
Arguments
- mat1
A numeric or character matrix or data frame, required.
- NA.color
character,'grey'; the color for missing values in
mat1
,rowAnnoDf
, orcolmAnnoDf
. If missing values are present, a square ofNA.color
will be added to the legend.- whiteValue
Numeric,
NULL
; it is the value of the white or middle color in the legend ifmat1
is numeric andcolMap
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 inmat1
area
,b
, andc
.For numeric
mat1
,colMap
is a numeric vector, i.e.c('blue'= NA,'green'=5, 'red'=10)
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 bec("green4", "white", "red")
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.One or both of the first and last values of
colMap
can be supplied as NA; then outliers will be auto-computed ifresetOutliers
isTRUE
.
- 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 assumescluster_rows
andcluster_columns
areTRUE
; so do NOT explicitly set those two arguments again. To also split, i.e. columns, setcolumn_split = nColmCluster
.- rowAnnoDf, colmAnnoDf
matrix or data frame,
NULL
; annotation for row or column. The rows of therowAnnoDf
/colmAnnoDf
should be of the same length and order of the row/column ofmat1
.- rowAnnoPara, colmAnnoPara
list,
list(na_col = NA.color)
; passed toComplexHeatmap::rowAnnotation()
orComplexHeatmap::columnAnnotation()
- rowAnnoColMap, colmAnnoColMap
list,
list()
; 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 parametercolMap
.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 usesComplexHeatmap::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. bycolumn_order()
However, it should be
FALSE
if the returned heatmap fromcHeatmap()
will be concatenated with other heatmaps.
- resetOutliers
logical,
is.numeric(mat1)
; outliers in numericmat1
can stretch the whole color scale. IfTRUE
, the bounds of the legend will be reset to the max or min values excluding them; for example, the legend ofc(10, 0.1, 0, 0.2)
will be from0
to0.2
with the labels0
and>0.2
.- clusterUsingResetValues
logical,
FALSE
; should the clustering of rows and columns use the reset values of outliers?- cellFun
NULL
; it is used to display info for individual cells; text info can be formatted bycellFontSize
andcellFontColor
. 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 cellcellFun = function(x){if(x > 10) x}
: display the value of cells whose values are greater than 10cellFun = function(x){if(x > 10) '?'}
: display the '?' signcellFun = function(x){if(x > 10) list('rect',col='black',lwd=2)}
: color the edges black and set line width as 2. Check the parameters ofgrid::gpar()
for more controls.
A character vector or list:
cellFun = 'o'
: display the values of all the outliers inmat1
if anycellFun = c('o','+')
: display the '+' sign instead of the value at the outlier cellscellFun=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 parametercell_fun
ofComplexHeatmap::Heatmap()
directly.- cfMat
mat1
; the matrix for the cells incellFun
; it should have the same dimension asmat1
. It gives the option of using a different matrix for the evaluation ofcellFun
and display its results on top of the heatmap frommat1
.- 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: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'))
; seegrid::grid.points()
for details. Forgrid.point
, it can also be simply coded aslist('grid.points',size = 0.3,pch=1,col='black')
; parametercol
and followed items are forgpar()
.list('grid.lines',gp=grid::gpar(col='black',lwd = 2))
; seegrid::grid.lines()
for details. Forgrid.lines
, it can also be simply coded aslist('grid.lines',col='black',lwd = 2)
parametercol
and followed items are forgpar()
.list( list('grid.points',size = 0.3,col='black'), list('grid.lines',col='black',lwd = 2) )
for multiple drawings
a matrix containing the data to make the drawing, its number of columns
an integer vector specifying the rows to make the drawing; if
NULL
, it means all the rows of mat1 and assumesnrow() == nrow(mat1)
for the supplied matrix at #2
See the parameter
layer_fun
ofComplexHeatmap::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 breaks1
; equal distance among breaksa 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 withinunname(colMap)
.- legendTickLabels
character, NULL; the label of legend tick; should be the same length as the
legendTicks
; use ” to skip a tick.- ...
passed to
ComplexHeatmap::Heatmap()
Value
a ComplexHeatmap::HeatmapList object if drawHeatmap, or a ComplexHeatmap::Heatmap object otherwise.
Details
Here are the features:
Automatic or manual setting of the values of outliers in the input matrix so that the color scale of the heatmap is not dominated by those outliers
The option to set the color-value mappings in the heatmap legend
Automatic coloring of the dendrogram
Easy highlight or display of the values of certain cells
Discrete color-value mapping for integer matrices containing few unique values
Clustering of the character matrix based on the orders of characters
Interface to plot across rows
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.