ComplexHeatmap cell function with bivariant color

cell_fun_bivariate(
  m,
  prefix = "",
  suffix = "",
  cex = 1,
  col_hm,
  outline = FALSE,
  outline_style = c("none", "contrast", "lighter", "darker", "black", "same"),
  abbrev = FALSE,
  show = NULL,
  rot = 0,
  sep = "\n",
  mcolor = NULL,
  pch = NULL,
  size_fun = NULL,
  size_by = 1,
  grid_color = "grey80",
  type = c("bivariate", "univariate"),
  verbose = FALSE,
  ...
)

Arguments

m

list of 2 or more matrix objects. The first two matrix objects are used for the bivariate color.

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

col_hm

function whose first two arguments accept numeric values, and which returns a single color. Note that when mcolor is provided, this argument is ignored.

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.

show

numeric indicating which list elements in m should be used to formulate a cell label, or NULL to use no label.

rot

numeric rotation in degrees, to rotate labels inside each heatmap cell. Mainly useful for heatmaps with extremely tall cells, use rot=90 for vertical text.

sep

character string used as a separator between multiple labels inside each cell, used only when show has more than one value.

mcolor

character matrix of R colors, with same nrow() and ncol() or each matrix in m. When mcolor is supplied, the colors are used directly, and col_hm is not used.

type

character string indicating whether the color function uses bivariate or univariate logic. This argument is intended to allow this function to be used in both scenarios for consistency.

...

additional arguments are passed to col_hm() to allow custom options relevant to that function.

Details

This function serves as a convenient method to use a bivariate color scale (biscale) to color heatmap cells.

See:

  • https://kwstat.github.io/pals/

  • https://nowosad.github.io/post/cbc-bp2/

  • https://cran.r-project.org/web/packages/biscale/vignettes/biscale.html

This function takes two numeric data matrices, a color function that accepts two numeric values as input and returns a color.

This function can also optionally display a text label inside each heatmap cell, use argument show to indicate which matrix or matrices in m to use for the label.

Examples

set.seed(12);
m <- matrix(rnorm(36)*2.5, ncol=4)
colnames(m) <- LETTERS[1:4]
rownames(m) <- letters[1:9]
m2 <- m;
m2[] <- abs(rnorm(36)*3);
mcolor <- matrix(ncol=3,
   c("white", "white", "white",
   "royalblue4", "gold", "red"),
   byrow=TRUE);
col_bivariate <- colorRamp2D(
   column_breaks=seq(from=-2, to=2, length.out=3),
   row_breaks=seq(from=0, to=5, length.out=2),
   mcolor);
display_colorRamp2D(col_bivariate)


# the heatmap can be created in one step
hm <- ComplexHeatmap::Heatmap(m * m2,
   border=TRUE,
   col=col_bivariate,
   heatmap_legend_param=list(
      color_bar="discrete",
      border=TRUE,
      at=-4:4),
   cell_fun=cell_fun_bivariate(list(m, m2),
      col_hm=col_bivariate,
      prefix=c("-log10P: ", "z-score: "),
      show=2:1),
   show_heatmap_legend=FALSE,
)
#> Warning: <anonymous>: ... may be used in an incorrect context: ‘col_hm(x = cell_value1, y = cell_value2, ...)’ (/Users/wardjm/Projects/Ward/multienrichjam/R/jamenrich-bivariatecolor.R:355-357)

lgds <- make_legend_bivariate(col_bivariate,
   ylab="-log10pvalue",
   xlab="z-score");
#> Loading required namespace: gridtext
ComplexHeatmap::draw(hm, annotation_legend_list=lgds)


lgds <- make_legend_bivariate(col_bivariate,
   row_breaks=seq(from=0, to=1, by=0.25),
   ylab="-log10pvalue");
ComplexHeatmap::draw(hm, annotation_legend_list=lgds)


# heatmap using point circles
ctmax <- 6;
point_size_max <- 12;
point_size_min <- 1;
size_fun_custom <- approxfun(
   x=c(1, ctmax),
   yleft=0,
   ties="ordered",
   yright=point_size_max,
   y=c(1,
      point_size_max));
ct_ticks <- seq(from=0, to=6);
ct_tick_sizes <- size_fun_custom(ct_ticks);

hm2 <- ComplexHeatmap::Heatmap(m * m2,
   border=TRUE,
   col=col_bivariate,
   heatmap_legend_param=list(
      color_bar="discrete",
      border=TRUE,
      at=-4:4),
   cell_fun=cell_fun_bivariate(list(m, m2),
      pch=21,
      size_fun=size_fun_custom,
      size_by=2,
      outline_style="black",
      col_hm=col_bivariate,
      prefix=c("-log10P: ", "z-score: "),
      show=NULL),
   show_heatmap_legend=FALSE,
)
#> Warning: <anonymous>: ... may be used in an incorrect context: ‘col_hm(x = cell_value1, y = cell_value2, ...)’ (/Users/wardjm/Projects/Ward/multienrichjam/R/jamenrich-bivariatecolor.R:355-357)
ComplexHeatmap::draw(hm2, annotation_legend_list=lgds)