Skill: 气泡图生成器 (bubble-plot)#

基于基因表达矩阵数据，生成按 细胞类型 × 癌种 分组的气泡图（dot plot）。

何时使用#

• 用户上传 TSV/CSV 表达数据文件，并要求画气泡图、dot plot、泡泡图
• 用户说"画气泡图"、"bubble plot"、"dot plot"并提供了数据文件
• 用户提供数据文件和基因列表，要求可视化表达模式

常见触发词#

• 画气泡图
• bubble plot
• dot plot
• 泡泡图
• 气泡图可视化
• 表达气泡图

执行清单#

1. 检查数据与环境#

• 确认用户提供了数据文件（TSV/CSV）
• 确认文件已下载到工作目录
• 确认 Python 3 + pandas + matplotlib 已安装（缺失时 pip3 install --break-system-packages pandas matplotlib）

2. 了解数据结构#

读取文件前几行，识别以下关键列：

角色识别关键词示例列名细胞类型majorCluster, cell_type, cluster``majorCluster组织类型tissue, class, condition, group``tissue癌种cancerType, cancer_type, disease``cancerType基因表达所有数值型非元数据列FOLR1, TACSTD2, MET ...

• 如果用户指定了基因列表，只画指定的
• 如果用户未指定，自动检测所有数值型非元数据列
• 将 Adjacent 等正常组织名称统一映射为 Normal

3. 运行脚本#

bash

# 基本用法 — 自动检测所有基因
python3 skills/bubble-plot/bubble_plot.py <data.tsv>

# 只画指定基因
python3 skills/bubble-plot/bubble_plot.py <data.tsv> --genes FOLR1 TACSTD2 MET

# 自定义列名（如果自动检测失败）
python3 skills/bubble-plot/bubble_plot.py <data.tsv> --genes FOLR1 MET --cell-col CellType --cancer-col Disease

# 不按组织类型拆分
python3 skills/bubble-plot/bubble_plot.py <data.tsv> --no-split-tissue

# 自定义输出目录和分辨率
python3 skills/bubble-plot/bubble_plot.py <data.tsv> -o my_plots --dpi 600

4. 输出文件#

• 默认输出到 bubble_plots/ 目录
• 每个基因 × 组织类型 = 1 个 PNG（300dpi）+ 1 个 PDF
• 文件命名： {基因}_dotplot_{Normal|Tumor}.{png|pdf}

5. 向用户报告结果#

• 列出生成的文件清单和大小
• 如果有基因在数据中不存在，明确告知并跳过
• 展示 1-2 张关键图的预览

参数说明#

参数默认值说明input必填输入 TSV 或 CSV 文件路径--genes / -g自动检测要画的基因名列表--cell-col自动检测细胞类型列名--cancer-col自动检测癌种/疾病列名--tissue-col自动检测组织类型列名--split-tissueTrue按组织类型拆分画图--no-split-tissue-不拆分，所有数据画一张--outdir / -o``bubble_plots输出目录--dpi300PNG 分辨率

图例说明#

• 气泡颜色：标准化平均表达量（0-1，红=高，蓝=低，RdBu_r 色谱）
• 气泡大小：阳性细胞百分比（该细胞类型中表达量 > 0 的比例）

自检#

• 数据文件是否已确认下载到本地
• 基因列名是否与数据中一致（区分大小写）
• tissue 列中 Adjacent 是否已映射为 Normal
• 输出是否包含 PNG 和 PDF 两种格式
• 缺失的基因是否已告知用户