shield_lock
JinDaGe
← Back to skills
extension
Category: Data & AnalyticsNo API key required

基因表达热图美化工具

用于美化基因表达热图的专业工具，自动添加聚类树状图、颜色注释条带，并智能优化行/列标签布局，支持导出 PDF、PNG、SVG 等发表级图像。以下场景也会触发本技能："帮我美化这个热图""给这个基因表达矩阵生成一张聚类热图""帮我给热图加上分组注释色带""这个热图标签太挤了帮我调整一下"。

personAuthor: aipoch-aihubclawhub
open_in_newRepositorydownloadDownload package

基因表达热图美化工具

用于基因表达热图的专业美化工具，自动添加聚类树状图、颜色注释条带，并智能优化标签布局。

输入校验

本技能接受：包含基因表达矩阵的 CSV 文件（基因为行、样本为列），用于生成和美化热图。

如果用户的请求不涉及热图生成或基因表达可视化——例如要求进行差异表达分析、统计检验，或生成其他类型的图表——不要继续执行。请回复：

"heatmap-beautifier 专注于从表达矩阵数据生成并美化基因表达热图。您的请求似乎超出了本技能的范围。请提供 CSV 格式的表达矩阵文件，或使用更合适的工具来完成您的任务。"

当请求超出范围、缺少必需的 CSV 输入，或需要引入未经确认的假设时，不要继续执行工作流。对于缺失的输入，请明确说明具体缺少哪些字段。

快速检查

python -m py_compile scripts/main.py
python scripts/main.py --help
# 最小可运行示例（需准备一个小型 CSV 表达矩阵）：
python scripts/main.py -i expression_matrix.csv -o test_heatmap.pdf

脚本本身没有内置演示/--demo 模式，运行前需要提供真实的 CSV 表达矩阵文件（见下方"输入数据格式"）。

适用场景

  • 为基因表达热图添加聚类树状图和注释条带并进行美化
  • 生成发表级热图输出（PDF、PNG、SVG 等），并优化标签布局
  • 为表达矩阵添加行/列注释色带
  • 统一稿件图表的热图风格

工作流程

  1. 校验输入 —— 在开始处理前先确认请求是否在范围内。
  2. 确认用户目标、必需输入以及不可协商的约束条件。
  3. 使用打包脚本路径，或在仅有实际可用输入的情况下走文档化的推理路径。
  4. 返回结构化结果，清晰区分假设、交付物、风险与未解决事项。
  5. 如果执行失败或输入不完整，切换到回退路径，并明确说明具体是什么阻碍了完整交付。

功能特性

  • 自动聚类：基于层次聚类自动添加行/列聚类树状图
  • 注释条带：支持多个颜色注释条带（样本分组、基因分类等）
  • 智能标签：自动计算最优字号，避免行/列标签重叠
  • 灵活配色：内置多种专业科研配色方案
  • 导出选项：支持 PDF、PNG、SVG、EPS、TIFF 格式（根据输出文件的扩展名自动判断，遇到不支持的扩展名会回退为 PDF）

依赖项

pip install seaborn matplotlib scipy pandas numpy

用法

基础用法（Python API）

import sys
sys.path.insert(0, "scripts")
from main import HeatmapBeautifier

hb = HeatmapBeautifier()
hb.create_heatmap(
    data_path="expression_matrix.csv",
    output_path="output/heatmap.pdf"
)

命令行用法

python scripts/main.py \
    -i expression_matrix.csv \
    -o heatmap.pdf

python scripts/main.py \
    -i expression_matrix.csv \
    -o heatmap.pdf \
    --row-cluster \
    --col-cluster \
    --row-annot row_annot.json \
    --col-annot col_annot.json \
    --title "基因表达情况"

文档修正说明：源版本 SKILL.md 记录了脚本中实际不存在的选项，包括 --demo、--output-json、--format、--data-path/-d，以及参数名 --row-annotations/--col-annotations（实际参数名为 --row-annot/--col-annot）。本文档已按 scripts/main.py 中 argparse 的真实定义重新核对并修正上述示例和参数表。

参数

| 参数 | 类型 | 默认值 | 是否必需 | 说明 | |-----------|------|---------|----------|-------------| | -i, --input | string | - | 是 | 输入表达矩阵文件路径（CSV） | | -o, --output | string | - | 是 | 输出图像路径，扩展名决定导出格式 | | -t, --title | string | 基因表达热图 | 否 | 图表标题 | | --cmap | string | RdBu_r | 否 | 配色方案 | | --center | float | 0 | 否 | 颜色映射中心值 | | --vmin | float | 无（按数据自动确定） | 否 | 颜色刻度最小值 | | --vmax | float | 无（按数据自动确定） | 否 | 颜色刻度最大值 | | --row-cluster | flag | 关闭 | 否 | 启用行聚类 | | --col-cluster | flag | 关闭 | 否 | 启用列聚类 | | --row-annot | string | - | 否 | 行注释 JSON 文件路径 | | --col-annot | string | - | 否 | 列注释 JSON 文件路径 | | --standard-scale | string | 无 | 否 | 标准化方式：row、col | | --z-score | int | 无 | 否 | Z-score 标准化：0（按行）、1（按列） | | --figsize | 两个浮点数 | 无（按数据量自动计算） | 否 | 图像尺寸（宽 高，单位英寸） | | --dpi | int | 300 | 否 | 输出分辨率（每英寸点数） | | --hide-row-labels | flag | 关闭 | 否 | 隐藏行标签 | | --hide-col-labels | flag | 关闭 | 否 | 隐藏列标签 | | --rotate-col | float | 45 | 否 | 列标签旋转角度 | | -v, --verbose | flag | 关闭 | 否 | 保留参数，当前版本对输出无实际影响 |

--input 和 --output 均为必需参数。

重要提示（行为差异）：--row-cluster/--col-cluster 在命令行中是 store_true 开关，如果不显式传入，命令行调用默认不启用聚类（不会绘制树状图）。这与 HeatmapBeautifier.create_heatmap() 方法本身的默认值不同——直接通过 Python API 调用该方法且不传参时，row_cluster/col_cluster 默认为 True（开启聚类）。请根据实际调用方式（命令行 vs. Python API）确认聚类是否会生效。

输入数据格式

表达矩阵（CSV）

,sample1,sample2,sample3,sample4
Gene_A,2.5,-1.2,0.8,-0.5
Gene_B,-0.8,1.5,-2.1,0.3
Gene_C,1.2,0.5,-0.7,1.8
  • 第一列：基因名称（行索引）
  • 第一行：样本名称（列名）
  • 数据内容：表达值（例如 log2 fold change、TPM、FPKM）

配色方案

脚本内置以下命名配色方案（cmap 参数可直接使用任意有效的 matplotlib/seaborn 配色名，此处仅列出内置说明中收录的选项）：

  • "RdBu_r" —— 红蓝配色（经典差异表达配色）
  • "viridis" —— 黄紫配色（适合连续型数据）
  • "RdYlBu_r" —— 红黄蓝配色
  • "coolwarm" —— 冷暖配色
  • "seismic" —— 地震图配色
  • "bwr" —— 蓝白红配色
  • "Spectral_r" —— 光谱配色
  • "BrBG_r" —— 棕绿配色

后两项（Spectral_r、BrBG_r）在源文档中未列出，但实际存在于脚本 COLOR_PALETTES 字典中，已补充到此列表。

错误处理

  • 如果必需输入缺失，明确说明具体缺少哪些字段，只索取最少的补充信息。
  • 如果任务超出文档化的范围，应停止执行，而不是猜测或擅自扩大任务范围。
  • 如果 scripts/main.py 执行失败，报告失败发生的具体位置，总结哪些部分仍可安全完成，并提供人工回退方案。
  • 不得编造文件、引用、数据、检索结果或执行结果。
  • 异常处理：load_data() 中的 CSV 解析使用 except (pd.errors.ParserError, UnicodeDecodeError, ValueError) 而非裸露的 except:，避免误吞其他异常。
  • 错误传播：FileNotFoundError 和 ValueError 在 main() 中通过 try/except (FileNotFoundError, ValueError) as e: print(f'错误：{e}', file=sys.stderr); sys.exit(1) 捕获，并以退出码 1 输出到标准错误流。

文档修正说明：源版本 SKILL.md 声称上述异常处理与错误传播已经实现，但对照实际脚本发现 load_data() 中用的是裸露的 except:，且 main() 中完全没有 try/except 包裹、也没有 import sys，任何 FileNotFoundError 都会直接抛出未处理的原始 traceback。本次本地化已在打包脚本中修复了这两处真实缺陷（补充精确的异常类型、补充 import sys 与 main() 中的 try/except），使脚本行为与本文档描述一致。

回退方案

如果 scripts/main.py 执行失败或所需输入不完整：

  1. 报告确切的失败位置和错误信息。
  2. 说明哪些工作仍可完成（例如，仅做数据校验而不渲染图像）。
  3. 人工回退：确认 CSV 格式是基因为行、样本为列，然后使用最简选项重新运行：python scripts/main.py -i data.csv -o out.png。
  4. 若怀疑聚类未生效，检查是否遗漏了 --row-cluster/--col-cluster 开关（见上方"重要提示"）。
  5. 不得编造执行结果或文件内容。

输出要求

每次最终回复在相关情况下都应明确包含以下内容：

  • 目标或所需交付物
  • 使用的输入及引入的假设
  • 工作流程或决策路径
  • 核心结果、建议或交付物
  • 约束、风险、注意事项或验证需求
  • 未解决事项及下一步检查

回复模板

对于非简单请求，使用以下固定结构：

  1. 目标
  2. 收到的输入
  3. 假设
  4. 工作流程
  5. 交付物
  6. 风险与限制
  7. 下一步检查

对于压力测试/多约束请求，还应包含：

  • 约束清单（合规性、性能、错误路径）
  • 未解决事项及明确的阻塞原因

如果请求较为简单，可以精简结构，但仍需在影响正确性时明确说明假设和限制。

说明

  1. 建议先对数据进行 log2 转换或标准化处理
  2. 大型数据集（超过 5000 行）处理时间可能较长
  3. 当行/列数量过多时，部分标签会被自动隐藏
  4. 脚本调用 sns.clustermap() 时未显式传入 method 参数，实际默认聚类方式是欧氏距离（Euclidean distance）+ 平均距离法（average linkage），并非源文档中所述的 Ward 法，此处已修正