bio-data-visualization-heatmaps-clustering
Build clustered heatmaps for expression matrices and other features-by-samples data with rigorous distance/linkage/scaling choices, robust color mapping, optimal leaf ordering, and ComplexHeatmap/pheatmap/seaborn rendering. Covers the ward.D vs ward.D2 trap, the row-vs-column scaling decision, multi-track annotations, oncoPrint, and raster rendering for large matrices. Use when visualizing expression patterns across samples or identifying co-regulated clusters.
npx skills add BioTender-max/awesome-bio-agent-skills --skill heatmaps-clustering --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
Directs the agent to render clustered heatmaps for feature-by-sample data, requiring explicit decisions on data scaling, distance metrics, linkage methods, leaf ordering, color mapping, and rendering package. It covers practical considerations for large matrices, multi-track annotations, OncoPrint integration, and obtaining publication-ready figures with appropriate rasterization and annotation tracks.
How it works
The skill instructs choosing and applying: (1) data scaling (row z-score, raw, or robust quantile clipping); (2) distance metric (euclidean, correlation-based distance, or manhattan); (3) linkage criterion (ward.D2, complete, average); (4) leaf ordering (default vs optimal leaf ordering via seriation); (5) color mapping (robust bounds, symmetric diverging palettes, and perceptual colormaps); (6) package and function usage (R: ComplexHeatmap::Heatmap or pheatmap::pheatmap; Python: seaborn.clustermap, scanpy.pl.heatmap); and (7) rendering controls (Heatmap with draw() for non-interactive contexts, use_raster or rasterized cell layer for large matrices).
The skill also provides concrete code patterns, including how to compute bounds for color mapping, how to define HeatmapAnnotation and rowAnnotation for metadata, and how to apply clustering settings for both rows and columns. It emphasizes explicit Ward2 usage (ward.D2) and includes warnings about non-interactive rendering in R scripts, suggesting wrap in draw() to ensure output.
When to use it
Use when visualizing expression patterns across samples or identifying co-regulated clusters, especially when handling annotation tracks, large matrices, and the need for reproducible clustering given distinct scaling/distance/linkage choices.
What it can touch
- ComplexHeatmap
- pheatmap
- seaborn (Python clustermap)
- scanpy.pl.heatmap
- R graphics rendering via draw()
- Annotation objects: HeatmapAnnotation, rowAnnotation
- Color mapping utilities: colorRamp2 and bounds calculation
Caveats
- Warns about the Ward method confusion between ward.D and ward.D2; explicitly requires ward.D2 for consistent results.
- Notes that outliers can distort color scales; recommends quantile-based clipping for robust visualization.
- Highlights that bare Heatmap() in non-interactive contexts may not render without draw().
- Contains cautions about Z-score on sparse matrices and batch effects affecting distance metrics.
- License: NOASSERTION
## Version Compatibility Reference examples tested with: ComplexHeatmap 2.18+, pheatmap 1.0.13 (still maintained as of 2025-06), circlize 0.4.16+, seaborn 0.13+, scipy 1.12+, scanpy 1.10+, ggplot2 3.5+. Before using code patterns, verify installed versions match. If versions differ: - Python: `pip show <package>` then `help(module.function)` to check signatures - R: `packageVersion('<pkg>')` then `?function_name` to verify parameters If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying. # Heatmaps and Hierarchical Clustering **"Make a clustered heatmap"** -> Render an expression / feature matrix as a colored grid with hierarchical-clustering dendrograms, after committing to (a) how to scale the data (row z-score vs raw vs robust), (b) which distance metric (Euclidean vs correlation vs Manhattan), (c) which linkage criterion (ward.D2 vs complete vs average), (d) how to order the leaves (default vs optimal leaf ordering), (e) how to map values to color (sequential vs diverging, robust quantile bounds), and (f) which package can handle the matrix size and annotation complexity. - R
- Version Compatibility
- The ward.D vs ward.D2 Trap (Murtagh-Legendre 2014)
- Decision Tree by Scenario
- Color Mapping -- The Quietly Most-Important Choice
- Optimal Leaf Ordering (Bar-Joseph 2001)
- Annotation Tracks -- ComplexHeatmap as the Reference
- The draw() requirement (silent failure)
- seaborn.clustermap (Python)
- OncoPrint -- The Specialized Mutation-Matrix Heatmap
- Per-Method Failure Modes
- ward.D used when ward.D2 was intended
- One outlier compresses the color scale
- ComplexHeatmap silently produces no output in a script
- Clustering applied to ordered conditions
What does the bio-data-visualization-heatmaps-clustering skill do?
Build clustered heatmaps for expression matrices and other features-by-samples data with rigorous distance/linkage/scaling choices, robust color mapping, optimal leaf ordering, and ComplexHeatmap/pheatmap/seaborn rendering. Covers the ward.D vs ward.D2 trap, the row-vs-column scaling decision, multi-track annotations, oncoPrint, and raster rendering for large matrices. Use when visualizing expression patterns across samples or identifying co-regulated clusters.
How do I install it?
Run `npx skills add BioTender-max/awesome-bio-agent-skills --skill heatmaps-clustering --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From BioTender-max/awesome-bio-agent-skills, a repository with 135 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.