火山图标注工具 (ID: 148)

使用排斥算法自动识别并标注火山图中最显著的前 10 个基因，防止标签重叠。

何时使用

当任务需要在火山图中自动标注最显著的基因并使用排斥算法防止重叠时，使用此技能。
当数据分析任务需要明确的假设、有界的范围以及可复现的输出格式时，使用此技能。
当你需要为缺失的输入、执行错误或部分证据提供有文档记录的后备方案时，使用此技能。

主要功能

相关细节参见上方的 ## Features。

与以下范围对齐的聚焦工作流：使用可复现的工作流程、明确的验证机制和结构化输出，借助 volcano-plot-labeler 分析数据，以便得出可供审阅的解读结果。
打包的可执行路径：scripts/main.py。
references/ 中提供了针对特定任务的参考材料。
结构化的执行路径,旨在保持输出的一致性和可审阅性。

依赖项

相关细节参见上方的 ## Prerequisites。

Python:3.10+。当前打包技能的仓库基线。
matplotlib:unspecified。在 requirements.txt 中声明。
numpy:unspecified。在 requirements.txt 中声明。
pandas:unspecified。在 requirements.txt 中声明。

示例用法

相关细节参见上方的 ## Usage。

cd "20260318/scientific-skills/Data Analytics/volcano-plot-labeler"
python -m py_compile scripts/main.py
python scripts/main.py --help

示例运行计划:

确认用户输入、输出路径以及任何必需的配置值。
如果脚本使用固定设置,编辑文件内的 CONFIG 块或文档中记录的参数。
使用验证过的输入运行 python scripts/main.py。
检查生成的输出,并返回最终产物及所指出的任何假设。

实现细节

相关细节参见上方的 ## Workflow。

执行模型:验证请求、选择打包的工作流,并生成有界的可交付成果。
输入控制:在运行任何脚本之前,先确认源文件、范围限制、输出格式和验收标准。
主要实现入口:scripts/main.py。
参考指导:references/ 包含支持性的规则、提示或检查清单。
需先明确的参数:输入路径、输出路径、范围筛选条件、阈值以及任何领域特定的约束。
输出规范:保持结果可复现,明确指出假设,并避免未记录的副作用。

快速检查

在进行更深入的执行之前,使用此命令验证打包脚本的入口点是否可以被解析。

python -m py_compile scripts/main.py

审计就绪命令

使用以下具体命令进行验证。它们是自成一体的,有意避免使用占位符路径。

python -m py_compile scripts/main.py
python scripts/main.py --help
python scripts/main.py --input "Audit validation sample with explicit symptoms, history, assessment, and next-step plan."

工作流程

在进行详细工作之前,先确认用户目标、所需输入以及不可协商的约束条件。
验证请求是否符合文档中记录的范围,如果任务需要不受支持的假设,则提前停止。
仅使用实际可用的输入,使用打包的脚本路径或文档中记录的推理路径。
返回结构化的结果,区分假设、可交付成果、风险和未解决的事项。
如果执行失败或输入不完整,切换到后备路径,并明确说明具体是什么阻碍了完全完成。

功能特性

智能基因选择:根据 p 值和倍数变化自动识别前 10 个最显著的基因
排斥算法:使用力导向定位来防止文本标签重叠
可自定义:可配置的阈值、标签样式和定位选项
多种输出格式:支持 PNG、PDF、SVG

安装

pip install pandas matplotlib numpy scipy

用法

基本用法

from volcano_plot_labeler import label_volcano_plot
import pandas as pd

# Load your data
df = pd.read_csv('differential_expression_results.csv')

# Generate labeled volcano plot
fig = label_volcano_plot(
    df,
    log2fc_col='log2FoldChange',
    pvalue_col='padj',
    gene_col='gene_name',
    top_n=10
)
fig.savefig('volcano_plot_labeled.png', dpi=300, bbox_inches='tight')

高级用法

from volcano_plot_labeler import label_volcano_plot

fig = label_volcano_plot(
    df,
    log2fc_col='log2FoldChange',
    pvalue_col='padj',
    gene_col='gene_name',
    top_n=10,
    pvalue_threshold=0.05,
    log2fc_threshold=1.0,
    figsize=(12, 10),
    repulsion_iterations=100,
    repulsion_force=0.05,
    label_fontsize=10,
    label_color='black',
    arrow_color='gray',
    save_path='output.png'
)

命令行用法

python scripts/main.py \
    --input data/deseq2_results.csv \
    --output volcano_labeled.png \
    --log2fc-col log2FoldChange \
    --pvalue-col padj \
    --gene-col gene_name \
    --top-n 10

输入格式

期望的 CSV/TSV 列:

log2FoldChange:Log2 倍数变化值
padj 或 pvalue:校正后的 p 值或原始 p 值
gene_name:基因标识符

算法

显著性计算

计算所有基因的 -log10(pvalue)
按综合得分对基因排序:|log2FC| * -log10(pvalue)
选择显著性最高的前 N 个基因

排斥算法

初始放置:将标签放置在基因坐标处
力的计算:
- 重叠标签之间的排斥力
- 将标签拉向其基因点的弹簧力
- 使标签保持在绘图区域内的边界力
迭代优化:更新位置进行 N 次迭代直至收敛
箭头绘制:绘制从标签到基因点的连接线

参数

| 参数 | 类型 | 默认值 | 描述 | |-----------|------|---------|-------------| | df | DataFrame | - | 输入数据 | | log2fc_col | str | 'log2FoldChange' | log2 倍数变化的列名 | | pvalue_col | str | 'padj' | p 值的列名 | | gene_col | str | 'gene_name' | 基因名称的列名 | | top_n | int | 10 | 要标注的顶部基因数量 | | pvalue_threshold | float | 0.05 | 用于着色的 p 值截断值 | | log2fc_threshold | float | 1.0 | 用于着色的 Log2FC 截断值 | | repulsion_iterations | int | 100 | 排斥算法的迭代次数 | | repulsion_force | float | 0.05 | 排斥力的强度 | | label_fontsize | int | 10 | 标签的字体大小 | | figsize | tuple | (10, 10) | 图形尺寸 |

输出

标注后的火山图,包含:
- 颜色编码的点(上调/下调/不显著)
- 带引导线的前 10 个基因标签
- 无重叠的文本标签

许可证

MIT

风险评估

| 风险指标 | 评估 | 等级 | |----------------|------------|-------| | 代码执行 | 本地执行 Python/R 脚本 | 中 | | 网络访问 | 无外部 API 调用 | 低 | | 文件系统访问 | 读取输入文件,写入输出文件 | 中 | | 指令篡改 | 标准提示词准则 | 低 | | 数据暴露 | 输出文件保存到工作区 | 低 |

安全检查清单

[ ] 无硬编码的凭据或 API 密钥
[ ] 无未授权的文件系统访问(../)
[ ] 输出不暴露敏感信息
[ ] 已具备提示注入防护措施
[ ] 已验证输入文件路径(无 ../ 路径遍历)
[ ] 输出目录限制在工作区内
[ ] 脚本在沙盒环境中执行
[ ] 错误消息已净化(不暴露堆栈跟踪)
[ ] 依赖项已审计

前提条件


# Python dependencies
pip install -r requirements.txt

评估标准

成功指标

[ ] 成功执行主要功能
[ ] 输出符合质量标准
[ ] 优雅地处理边界情况
[ ] 性能可接受

测试用例

基本功能:标准输入 → 预期输出
边界情况:无效输入 → 优雅的错误处理
性能:大型数据集 → 可接受的处理时间

生命周期状态

当前阶段:草稿
下次审查日期:2026-03-06
已知问题:无
计划改进:
- 性能优化
- 增加更多功能支持

输出要求

每个最终响应在相关时都应明确以下事项:

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

错误处理

如果缺少必需的输入,准确说明缺少哪些字段,并仅请求最少的额外信息。
如果任务超出文档记录的范围,应停止,而不是猜测或悄悄扩大任务范围。
如果 scripts/main.py 执行失败,报告失败点,总结仍可安全完成的部分,并提供手动后备方案。
不得虚构文件、引用、数据、搜索结果或执行结果。

输入验证

此技能接受符合 volcano-plot-labeler 文档记录用途的请求,且需包含足够的上下文以安全完成工作流程。

当请求超出范围、缺少关键输入或需要不受支持的假设时,不要继续工作流程。应回复:

volcano-plot-labeler 仅处理其文档记录的工作流程。请提供缺失的必需输入,或切换到更合适的技能。

响应模板

对于非简单的请求,使用以下固定结构:

目标
收到的输入
假设
工作流程
可交付成果
风险和限制
下一步检查

如果请求很简单,可以压缩结构,但在影响正确性时仍需明确说明假设和限制。

需收集的输入

必需输入:用户目标、主要数据或源文件,以及所需的输出格式。
可选输入:输出目录、格式偏好和验证约束。
如果必需的输入不可用,在继续之前先返回简短的澄清请求。

输出约定

返回简短摘要、主要可交付成果,以及任何对解读有实质性影响的假设。
如果执行只完成了部分,标明哪些成功、哪些失败,以及下一步的安全恢复措施。
将最终答案保持在此技能文档记录的范围内。

验证和安全规则

在执行之前验证标识符、文件路径和用户提供的参数。
不得虚构结果、指标、引用或下游结论。
当依赖项、凭据或必需输入缺失时,使用安全的后备行为。
对任何执行失败,提供简明的诊断和恢复路径。