ExpressionHeatmap: Generate an expression heatmap with customizable sample annotations and separate legend positions

This function creates a heatmap of Z-score scaled gene expression using the ComplexHeatmap package. Genes are displayed as rows and samples as columns. A color annotation bar is added on top based on specified metadata columns. The user can control the position of the heatmap color scale (scale_position) and the annotation legend (legend_position) independently.

Usage

ExpressionHeatmap(
  data,
  metadata = NULL,
  genes,
  annotate.by = NULL,
  annotation_colors = NULL,
  colorlist = list(low = "blue", mid = "white", high = "red"),
  cluster_rows = TRUE,
  cluster_columns = TRUE,
  title = NULL,
  titlesize = 20,
  scale_position = c("right", "top", "bottom"),
  legend_position = c("top", "right", "bottom"),
  show_row_names = TRUE,
  show_column_names = FALSE
)

Arguments

data: A numeric expression matrix where rows correspond to genes and columns to samples.
metadata: A data frame containing metadata for the samples. It must contain a column named "Sample" with sample IDs matching the column names of data.
genes: A character vector of gene names to include in the heatmap.
annotate.by: A character vector of metadata column names to be used for sample annotations (e.g., c("Condition", "Batch")). If provided, a color bar is added on top.
annotation_colors: Optional. A named list where each element corresponds to an annotation variable and provides a named vector mapping each unique level to a color. If not provided, default Brewer palettes are used.
colorlist: A named list specifying the colors for the heatmap (for scaled expression) with elements low, mid, and high. Default is list(low = "blue", mid = "white", high = "red").
cluster_rows: Logical; whether to cluster rows (default = TRUE).
cluster_columns: Logical; whether to cluster columns (default = TRUE). If FALSE, the columns are reordered based on the values in annotate.by.
title: A string specifying the main title of the heatmap.
titlesize: Numeric; font size of the heatmap title (default = 20).
scale_position: A character string specifying the position of the heatmap color scale. Options are "right" (default), "top", or "bottom". The scale legend will adopt a vertical orientation if on the right and horizontal if on top or bottom.
legend_position: A character string specifying the position of the annotation legend. Options are "top" (default), "right", or "bottom".
show_row_names: A character string specifying whether row names (genes) should be displayed.
show_column_names: A character string specifying whether column names (samples) should be displayed.

Value

A list containing:

data: The scaled expression matrix (Z-scores).
plot: The generated ComplexHeatmap object.

Examples

if (FALSE) { # \dontrun{
set.seed(123)
data_matrix <- matrix(rnorm(100), nrow = 10, ncol = 10)
rownames(data_matrix) <- paste0("Gene", 1:10)
colnames(data_matrix) <- paste0("Sample", 1:10)

metadata <- data.frame(Sample = colnames(data_matrix),
                       Condition = rep(c("A", "B"), each = 5),
                       Batch = rep(c("X", "Y"), times = 5),
                       stringsAsFactors = FALSE)

result <- ExpressionHeatmap(data_matrix, metadata, genes = rownames(data_matrix),
                            annotate.by = c("Condition", "Batch"),
                            annotation_colors = list(
                              Condition = c(A = "red", B = "blue"),
                              Batch = c(X = "green", Y = "purple")
                            ),
                            cluster_columns = FALSE,
                            title = "Expression Heatmap",
                            scale_position = "right",
                            legend_position = "top",
                            titlesize = 20)

# To display the heatmap:
result$plot
} # }