MultiEnrichment Heatmap of enrichment P-values

Source: R/jamenrich-plot.R

MultiEnrichment Heatmap of enrichment P-values

mem_enrichment_heatmap(
  mem,
  style = c("dotplot", "heatmap"),
  p_cutoff = mem$p_cutoff,
  min_count = 1,
  p_floor = 1e-10,
  point_size_factor = 1,
  point_size_max = 8,
  point_size_min = 2,
  row_method = "euclidean",
  column_method = "euclidean",
  name = "-log10P",
  row_dend_reorder = TRUE,
  row_dend_width = grid::unit(30, "mm"),
  row_fontsize = NULL,
  row_cex = 1,
  row_split = NULL,
  cluster_rows = TRUE,
  column_fontsize = NULL,
  column_cex = 1,
  cluster_columns = FALSE,
  sets = NULL,
  color_by_column = FALSE,
  cex.axis = 1,
  lens = 3,
  cexCellnote = 0,
  column_title = NULL,
  row_names_max_width = grid::unit(30, "cm"),
  column_names_max_height = grid::unit(30, "cm"),
  heatmap_legend_param = NULL,
  legend_height = grid::unit(6, "cm"),
  legend_cex = 1,
  apply_direction = FALSE,
  direction_cutoff = 0,
  gene_count_max = NULL,
  top_annotation = NULL,
  show = NULL,
  use_raster = FALSE,
  do_plot = TRUE,
  ...
)

Arguments

mem

list object created by multiEnrichMap(). Specifically the object is expected to contain enrichIM.

style

character string indicating the style of heatmap: "heatmap" produces a regular heatmap, shaded by log10(Pvalue); "dotplot" produces a dotplot, where the dot size is proportional to the number of genes. See function description for details on how to include the point size legend beside the heatmap. The main benefit of using "dotplot" style is that it also indicates the relative number of genes involved in the enrichment.

p_cutoff

numeric value of the enrichment P-value cutoff, by default this value is obtained from mem$p_cutoff to be consistent with the original multiEnrichMap() analysis. P-values above p_cutoff are not colored, and are therefore white. This behavior is intended to indicate pathways with P-value above this threshold did not meet the threshold, instead of pathways with similar P-values displaying with similar color.

min_count

numeric number of genes required for a pathway to be considered dysregulated.

p_floor

numeric minimum P-value used for the color gradient. P-values below this floor are colored with the maximum color gradient. This value is intended to be used in cases where one enrichment P-value is very low (e.g. 1e-36) to prevent all other P-values from being colored pale red-white and not be noticeable.

point_size_factor

numeric used to adjust the legend point size, since the heatmap point size is dependent upon the number of rows, the legend may require some manual adjustment to make sure the legend matches the heatmap.

point_size_min, point_size_max

numeric values which define the minimum and maximum point sizes, effectively defining the range permitted when style="dotplot".

row_method

character string of the distance method to use for row and column clustering. The clustering is performed by amap::hcluster().

name

character value passed to ComplexHeatmap::Heatmap(), used as a label above the heatmap color legend.

row_dend_reorder

logical indicating whether to reorder the row dendrogram using the method described in ComplexHeatmap::Heatmap(). The end result is minor reshuffling of leaf nodes on the dendrogram based upon mean signal in each row, which can sometimes look cleaner.

row_fontsize, column_fontsize

optional numeric arguments passed to ComplexHeatmap::Heatmap() to size row and column labels.

cluster_columns

logical indicating whether to cluster heatmap columns, by default columns are not clustered.

sets

character vector of sets (pathways) to include in the heatmap, all other sets will be excluded.

color_by_column

logical indicating whether to colorize the heatmap using mem$colorV as defined for each comparison. This option is currently experimental, and produces a base R heatmap using jamba::imageByColors().

cex.axis

numeric adjustment for axis labels, passed to jamba::imageByColors() only when color_by_column=TRUE.

lens

numeric value used in color gradients, defining the extent the color gradient is enhanced in the mid-ranges (positive lens), or diminished in the mid-ranges (negative lens). There is no quantitative standard measure for color gradient changes, so this option is intended to help adjust and improve the visual perception of the current data.

cexCellnote

numeric character expansion value used only when color_by_column=TRUE, used to adjust the P-value label size inside each heatmap cell.

column_title

optional character string with title to display above the heatmap.

row_names_max_width, column_names_max_height, heatmap_legend_param

arguments passed to ComplexHeatmap::Heatmap() and provided here for convenience.

top_annotation

HeatmapAnnotation as produced by ComplexHeatmap::HeatmapAnnotation() or NULL, used to display customized annotation at the top of the heatmap. The order of columns must match the order of columns in the data displayed in the heatmap.

use_raster

logical passed to ComplexHeatmap::Heatmap() indicating whether to rasterize the heatmap output, used when style="heatmap". Rasterization is not relevant to dotplot output since dotplot is drawn using an individual circle in each heatmap cell.

do_plot

logical indicating whether to display the plot with ComplexHeatmap::draw() or jamba::imageByColors() as relevant. The underlying data is returned invisibly.

...

additional arguments are passed to ComplexHeatmap::Heatmap() for customization.

Details

This function is a lightweight wrapper to ComplexHeatmap::Heatmap() intended to visualize the enrichment P-values from multiple enrichment results. The P-value threshold is used to colorize every cell whose P-value meets the threshold, while all other cells are therefore white.

The style argument controls whether a heatmap or dotplot is created. When style="dotplot" the cells are colored as usual but are drawn as circles sized proportional to the number of genes involved in enrichment. Because ComplexHeatmap::Heatmap() is used for this step, a separate point legend is returned as an attribute of the heatmap object.

To draw the dotplot heatmap including the point legend, use this form:

ComplexHeatmap::draw(hm,
   annotation_legend_list=attr(hm, "annotation_legend_list"))

Note that this function may be more easily applied through the wrapper function with the format mem_plot_folio(mem, do_which=1, ...). The wrapper function mem_plot_folio() performs hierarchical clustering of the underlying gene-pathway incidence matrix, which informs the clustering of enrichment results shown in this function mem_enrichment_heatmap(). Otherwise, this function will cluster pathways using only the enrichment P-values transformed with -log10(p). Generally, the clustering using the gene-pathway incidence matrix is more effective at representing biologically-driven pathway clusters.