Group-Level Expression Heatmap with Optional Dot Overlay

Computes mean expression per combination of group.by levels for the supplied features, scales across groups (z-score by default), and draws a ComplexHeatmap with:

Color fill = scaled mean expression
Dot overlay (optional) - dots sized by \ expressing each gene within each column group
Row split + textbox labels - rows grouped and annotated by feature_split categories
Column faceting - each level of column_split_by forms a panel; within every panel all group.by combinations are shown
Column annotation - one color bar per group.by variable (analogous to ComplexHeatmap's multi-bar top annotation)

Usage

GroupHeatmap(
  seurat_object,
  group.by,
  features,
  feature_split = NULL,
  feature_column = NULL,
  feature_group_column = NULL,
  column_split_by = NULL,
  assay = "RNA",
  layer = "data",
  scale_method = "zscore",
  add_dot = TRUE,
  add_bg = TRUE,
  dot_size = grid::unit(4, "mm"),
  pct_cutoff = 0,
  palette = "RdBu",
  color_scale = NULL,
  scale_limits = c(-2, 2),
  group_colors = NULL,
  column_split_colors = NULL,
  feature_split_colors = NULL,
  textbox_labels = TRUE,
  cluster_rows = TRUE,
  cluster_row_slices = FALSE,
  cluster_columns = FALSE,
  heatmap_params = list(show_row_names = TRUE, row_names_side = "right", row_names_gp =
    grid::gpar(fontsize = 8), show_row_dend = FALSE, column_names_side = "top",
    column_title = NULL),
  auto_draw = TRUE,
  legend_side = "right",
  width = grid::unit(5, "in"),
  height = grid::unit(7, "in"),
  auto_size = TRUE,
  pdf.width = NULL,
  pdf.height = NULL,
  output_dir = NULL,
  object_name = "",
  subset_name = "",
  file_name = NULL,
  timestamp = FALSE
)

Arguments

seurat_object

A Seurat object.

group.by

Character vector of metadata column(s) whose unique combinations become the heatmap columns (e.g. c("CellTypes", "Treatment")).

features

Either a character vector of gene names, or a data.frame. When a data.frame, the gene column is taken from feature_column and (if given) row groups from feature_group_column - so a marker table can be passed directly.

feature_split

Row-group labels. Either a named vector (names = gene symbols, values = group labels), or an unnamed vector the same length as features (matched by position). When supplied, rows are split and labeled. Ignored when features is a data.frame with feature_group_column set.

feature_column

Character or NULL. When features is a data.frame, the column holding gene names. NULL auto-detects (gene/feature/Genes/...) or uses the first column.

feature_group_column

Character or NULL. When features is a data.frame, the column holding row-group labels (becomes feature_split). NULL auto-detects (group/cluster/CellType/...) if present.

column_split_by

Optional metadata column used to facet (visually split) the columns into panels. May be one of the group.by variables or a separate one.

assay

Assay to use. Default "RNA".

layer

Layer for expression extraction. Default "data".

scale_method

"zscore" (default), "minmax", or "none".

add_dot

Logical. Overlay dots sized by \ TRUE.

add_bg

Logical. Draw a white disc behind each dot so it pops against dark expression colors. Default TRUE.

dot_size

Base dot size as a grid::unit object. Default grid::unit(4, "mm").

pct_cutoff

Minimum fraction expressing (0-1) to draw a dot. Default 0.

palette

RColorBrewer diverging palette for the expression color scale. Default "RdBu".

color_scale

Optional pre-built circlize::colorRamp2 object. Overrides palette.

scale_limits

c(min, max) for the color scale. Default c(-2, 2).

group_colors

Colors for group.by levels. Accepts:

A named list where each element is a named color vector for one group.by variable, e.g. list(CellType = ct_cols, Treatment = tx_cols).
A named vector when group.by has length 1 (backward-compatible).
NULL (default) - auto-assigned from PrepObject or Nour_pal.

column_split_colors

Named color vector for column_split_by levels.

feature_split_colors

Named color vector for feature_split categories (cosmetic; not currently used in cell_fun).

textbox_labels

Logical. Use anno_textbox when available (ComplexHeatmap ≥ 2.13). Default TRUE.

cluster_rows

Logical. Cluster rows within each split. Default TRUE.

cluster_row_slices

Logical. Cluster row slices. Default FALSE.

cluster_columns

Logical. Cluster columns within each split. Default FALSE.

heatmap_params

Named list of extra arguments forwarded to ComplexHeatmap::Heatmap().

auto_draw

Logical. Render automatically after building. Default TRUE.

legend_side

Where to place the legends. Default "right". Moves both the heatmap color legend and the annotation legends (row-split modules, top annotations) to the same side.

width

Heatmap body width, as a grid::unit or a bare numeric (interpreted as inches). When left at the default and auto_size = TRUE, the body width is derived from the number of columns. Default grid::unit(5, "in").

height

Heatmap body height (grid::unit or numeric inches). Auto-derived from the number of rows when left at the default and auto_size = TRUE. Default grid::unit(7, "in").

auto_size

Logical. When TRUE (default) and width / height are not explicitly supplied, size the heatmap body from the number of genes and column groups. The saved PDF is always sized to fit the longest row and column names regardless of this setting.

pdf.width, pdf.height

Numeric. PDF device width and height in inches. When supplied, these are passed directly to grDevices::pdf() and override all automatic size estimation. Use these when the heuristic sizing gets the device dimensions wrong (e.g. very wide heatmaps with many donors). NULL (default) keeps the automatic behavior.

output_dir

Directory to save a PDF. NULL = no file.

object_name

Prefix for output file names. Falls back to the object_name stored by PrepObject.

subset_name

Optional subset label inserted into the file name. Falls back to the subset_name stored by PrepObject.

file_name

Character or NULL. Base name (no extension) for the saved PDF. NULL (default) auto-deduces the name from object_name, subset_name, the features variable name, and the group.by / column_split_by variables.

timestamp

Logical. When TRUE, append a _YYYYMMDD-HHMMSS stamp to the saved file name so repeated runs are versioned instead of overwriting the previous PDF. Default FALSE.

Value

Invisibly, a named list:

heatmap: The Heatmap object.
expression_matrix: Scaled mean-expression matrix.
percent_matrix: Fraction expressing per column group.
column_groups: Data frame of all column combinations.
feature_split: The feature_split vector used.
dot_legend: The dot-size Legend object or NULL.

Multiple group.by variables

group.by may be a character vector of length > 1. The heatmap columns are the observed unique combinations of all listed variables, ordered by the first variable, then the second, etc. The top annotation automatically shows one color bar per variable.

column_split_by behavior

When column_split_by is supplied the function computes expression for every (group.by × column_split_by) combination found in the object. This means a CellType that appears in both "Vehicle" and "Drug" produces two columns (one per treatment), placed in their respective panels. This is the correct faceting behavior.