← Về thư mục
📄 / / profiles / r-and-d / raw_evidence / OpenAI4S / skills / bioskills / bio-data-visualization-heatmaps-clustering / references / usage-guide.md

Heatmaps and Hierarchical Clustering - Usage Guide

Overview

Heatmaps render a features-by-samples matrix as a colored grid with optional dendrograms. The choices that determine the biological story are scaling (row z-score vs raw vs robust), distance metric (Euclidean vs correlation vs Manhattan), linkage criterion (ward.D2 vs complete vs average), leaf ordering (default vs optimal), and color mapping (sequential vs diverging, robust bounds). ComplexHeatmap is the modern reference implementation; pheatmap remains maintained for simpler cases; seaborn.clustermap covers Python.

Prerequisites

install.packages(c('pheatmap', 'seriation', 'dendextend', 'circlize'))
BiocManager::install(c('ComplexHeatmap'))

pip install seaborn scipy pandas numpy

Quick Start

Tell your AI agent what you want to do: - "Make a clustered heatmap of my expression matrix with row z-score and ward.D2" - "Add column annotation tracks for condition and batch" - "Cluster columns within each treatment group, keeping treatment as the major split" - "Use a robust color scale clipped at the 1st-99th percentile" - "Render with optimal leaf ordering so visually adjacent rows are actually similar" - "Save as PDF with raster rendering for a 5000-row matrix"

Example Prompts

Bulk RNA-seq expression heatmap

"Build a publication-quality ComplexHeatmap of the top 500 variable genes, row-z-scored, with ward.D2 linkage on Euclidean distance. Add column annotation for condition and batch. Use a diverging Crameri 'vik' palette with symmetric bounds at the 1st-99th percentile."

Mutation matrix (OncoPrint)

"Make an OncoPrint of the recurrent gene mutations across the cohort, color-coded by alteration type (missense, truncating, copy gain, copy loss), sorted by mutation frequency."

Single-cell pseudobulk

"Aggregate the scRNA matrix to pseudobulk by cluster, then plot a heatmap of marker genes z-scored across clusters."

Sample correlation QC

"Compute pairwise sample correlations on the top-variable-gene matrix; plot as a symmetric heatmap to check for outlier samples and batch grouping."

Multi-heatmap concatenation

"Side-by-side heatmap of expression (z-score) and methylation (beta) for the same gene set, sharing the row order from expression clustering."

What the Agent Will Do

  1. Load the input matrix (expression, methylation, peak counts, or generic features-by-samples) and the metadata frame.
  2. Filter to the analysis subset - top-variable rows, DE hits, or a pre-specified gene list.
  3. Decide scaling: row z-score for cross-sample expression comparison; raw for absolute-interpretable data; robust for outlier-prone data.
  4. Decide distance: Euclidean for z-scored data; correlation for co-regulation discovery; binary for mutation matrices.
  5. Decide linkage: ward.D2 (default for most genomics); average for WGCNA-style co-expression; complete only when justified.
  6. Compute robust color bounds (1st-99th percentile of |matrix|); use symmetric bounds for diverging data.
  7. Optionally compute Optimal Leaf Ordering via seriation; pass dendrogram to ComplexHeatmap.
  8. Build column and row annotation tracks with explicit color lists.
  9. Render with draw() (NEVER bare Heatmap() in a script); set use_raster=TRUE, raster_quality=5 for matrices >2000 rows.
  10. Export PDF with cairo_pdf for vector text + raster cells.

Tips