cell_fun_bivariate: ComplexHeatmap cell function with bivariant color
In jmw86069/jamenrich: Analysis and Visualization of Multiple Gene Set Enrichments

cell_fun_bivariate

R Documentation

ComplexHeatmap cell function with bivariant color

Description

ComplexHeatmap cell function with bivariant color

Usage

cell_fun_bivariate(
  m,
  prefix = "",
  suffix = "",
  cex = 1,
  col_hm,
  outline = FALSE,
  outline_style = c("none", "darker", "contrast", "lighter", "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"),
  invert = FALSE,
  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
`outline_style`	`character` string indicating the type of outline to draw, which also requires `outline=TRUE`. Options: none: uses no outline even when `outline=TRUE` darker: always uses a darker color (or black) contrast: uses a contrasting color `setTextContrastColor()` lighter: always uses a lighter color (or white) black: always uses `"black"` same: use the same color as the fill color
`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.
`pch`	`numeric` point type, used only when `size_fun` is also defined. Together these arguments allow customized points.
`size_fun`	`function` used to define point size, only when `pch` is also defined. Together these arguments allow customized points.
`grid_color`	`character` valid R color used with `style="dotplot"` to draw lines through the center of each cell.
`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.
`invert`	`logical` indicating whether to invert the color fill, such that each cell is filled with color, and the circle is drawn empty on top.
`...`	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,
)

lgds <- make_legend_bivariate(col_bivariate,
   ylab="-log10pvalue",
   xlab="z-score");
ComplexHeatmap::draw(hm, annotation_legend_list=lgds)

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

# 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,
)
ComplexHeatmap::draw(hm2, annotation_legend_list=lgds)

jmw86069/jamenrich documentation built on Nov. 6, 2024, 7:07 p.m.