cell_fun_label: ComplexHeatmap cell function to label heatmap cells

In jmw86069/jamba: Jam Base Methods

ComplexHeatmap cell function to label heatmap cells

Description

ComplexHeatmap cell function to label heatmap cells

Usage

cell_fun_label(
  m,
  prefix = "",
  suffix = "",
  cex = 1,
  col_hm = NULL,
  outline = FALSE,
  abbrev = FALSE,
  show = NULL,
  rot = 0,
  sep = "\n",
  verbose = FALSE,
  ...
)

Arguments

m	numeric matrix or list of matrix objects. The first matrix object must be numeric and compatible with the color function col_hm.
prefix, suffix	character vectors that define a prefix and suffix for each value in m for each cell.
cex	numeric adjustment for the fontsize used for each label, which is multiplied by the default fontsize=10 to determine the fontsize.
col_hm	function as returned by circlize::colorRamp2() which should be the same function used to create the heatmap
outline	logical indicating whether to draw an outline around each heatmap cell
abbrev	logical indicating whether numeric values should be abbreviated using jamba::asSize(..., kiloSize=1000) which effectively reduces large numbers to k for thousands, M for millions (M for Mega), G for billions (G for Giga), etc.
verbose	logical indicating whether to print verbose output, specifically printing label information for position ⁠(1, 1)⁠. This output will only be seen when rendering or building the Heatmap object.
...	additional arguments are ignored.

Details

This function serves as a convenient method to add text labels to each cell in a heatmap produced by ComplexHeatmap::Heatmap(), via the argument cell_fun.

Note that this function requires re-using the specific color function used for the heatmap in the call to ComplexHeatmap::Heatmap().

This function is slightly unique in that it allows multiple labels, if m is supplied as a list of matrix objects. In fact, some matrix objects may contain character values with custom labels.

Cell labels are colored based upon the heatmap cell color, which is passed to jamba::setTextContrastColor() to determine whether to use light or dark text color for optimum contrast.

TODO: Option to supply a logical matrix to define a subset of cells to label, for example only labels that meet a filter criteria. Alternatively, the matrix data supplied in m can already be filtered.

TODO: Allow some matrix values that contain character data to use gridtext for custom markdown formatting. That process requires a slightly different method.

See Also

Other jam heatmap functions: heatmap_column_order(), heatmap_row_order()

Examples

# Examples require ComplexHeatmap Bioconductor/github package
# github:jokergoo/ComplexHeatmap
if (check_pkg_installed("ComplexHeatmap")) {

m <- matrix(rnorm(16)*2, ncol=4)
colnames(m) <- LETTERS[1:4]
rownames(m) <- letters[1:4]
col_hm <- circlize::colorRamp2(breaks=(-2:2) * 2,
   colors=c("navy", "dodgerblue", "white", "tomato", "red4"))

# the heatmap can be created in one step
hm <- ComplexHeatmap::Heatmap(m,
   col=col_hm,
   heatmap_legend_param=list(
      color_bar="discrete",
      border=TRUE,
      at=-4:4),
   cell_fun=cell_fun_label(m,
      col_hm=col_hm))
ComplexHeatmap::draw(hm)

# the cell label function can be created first
cell_fun <- cell_fun_label(m,
   outline=TRUE,
   cex=1.5,
   col_hm=col_hm)
hm2 <- ComplexHeatmap::Heatmap(m,
   col=col_hm,
   cell_fun=cell_fun)
ComplexHeatmap::draw(hm2)
}

jmw86069/jamba documentation built on Oct. 9, 2024, 10:52 a.m.