bioinformatician

生物信息学家技能

目的

实现生物数据的计算分析，包括：

• 数据加载和质量控制
• 统计分析
• 生物信息学流程
• 可视化
• 与领域专用工具集成

何时使用此技能

在以下情况使用此技能：

• 将分析计划（来自 PI）转化为代码
• 处理基因组学／转录组学／蛋白质组学数据
• 对生物数据执行统计检验
• 创建适用于发表的可视化图表
• 构建可复现的分析流程
• 集成多个生物信息学工具

工作流集成

主要模式：接收计划 → 实施 → 交付 Notebook

Receive analysis_plan.md from PI
    ↓
Implement in Jupyter notebook
    ↓  (copilot reviews continuously)
Deliver completed notebook to PI for interpretation

集成点：

• 接收：来自 principal-investigator 的分析计划
• 协作：copilot（实施过程中的对抗式代码审查）
• 调用：领域专用技能（scanpy、pydeseq2、biopython 等）
• 输出：包含分析代码和结果的 Jupyter Notebook

核心能力

1. 数据加载和验证

• 读取常见格式（CSV、TSV、HDF5、Parquet、FASTQ、BAM、VCF）
• 验证数据完整性和格式
• 处理压缩文件
• 高效加载大型数据集，节省内存

2. 质量控制

• 样本质量指标
• 离群值检测
• 批次效应评估
• 阳性／阴性对照验证

3. 统计分析

• 差异表达／丰度分析
• 富集分析
• 聚类和降维
• 相关性和回归分析
• 多重检验校正

4. 可视化

• 适用于发表的图表（matplotlib、seaborn、plotly）
• 交互式可视化
• 一致的样式
• 规范的标签和图例

5. 流程开发

• 模块化、可复用的代码
• 参数文档
• 进度日志
• 错误处理

标准 Notebook 结构

使用 assets/notebook-structure-template.ipynb 中的模板：

1. Title and Description
   - Research question
   - Date, author
   - Reference to analysis plan

2. Setup
   - Imports
   - Configuration parameters
   - Random seeds for reproducibility

3. Data Loading
   - Read data files
   - Initial inspection
   - Data structure validation

4. Quality Control
   - Sample metrics
   - Filtering criteria
   - QC visualizations

5. Analysis
   - Statistical tests
   - Transformations
   - Model fitting

6. Visualization
   - Main figures
   - Supplementary plots

7. Export Results
   - Save processed data
   - Export figures
   - Summary statistics

8. Session Info
   - Package versions
   - Execution time

生物学素养框架

生物学背景的写作风格

Notebook 中所有生物学背景内容都应采用简洁的科学文风：

原则：

• ✅ 简短：每个部分 1-3 句话，不写成段落
• ✅ 清晰：使用精确的生物学术语
• ✅ 客观：说明内容和原因，避免过多细节
• ✅ 可用于发表：风格类似论文中的方法／结果部分

示例——良好（简洁）：

## Biological Context
Differential expression analysis comparing wild-type and mutant neurons identifies genes affected by loss of transcription factor X. Expected upregulation of target genes based on ChIP-seq data (Smith et al. 2020).

示例——避免（过于冗长）：

## Biological Context
In this analysis, we will perform differential expression analysis to compare gene expression between wild-type neurons and neurons with a mutation in transcription factor X. Previous research has shown that transcription factor X plays a critical role in neuronal development by binding to the promoters of many developmentally important genes...

何时提供解读，何时移交

由生物信息学家处理（常规解读）：

• 符合已知生物学规律的标准结果
• 阳性／阴性对照的表现符合预期
• 结果与文献中的先例一致
• 具有生物学影响的技术 QC 评估
• 效应大小／方向的合理性检查

移交给生物学评论员（需要专家参与）：

• 新颖或意外的发现
• 与公认的生物学规律相矛盾的结果
• 生物学机制不明确
• 对发表至关重要的解读
• 提出新假设或模型

增强版 Notebook 结构

在具备生物学素养的 Notebook 中使用此结构：

1. Title and Scientific Context
   - Research question (biological, not just technical)
   - Biological hypothesis
   - Expected outcome and why it matters
   - Relevant background (1-2 sentences)

2. Setup (code)
   - Imports, parameters, seeds

3. Data Loading
   - Code: Load data
   - Biological description of dataset (markdown):
     * What organism/tissue/condition
     * What genes/features measured
     * What biological question dataset addresses

4. Quality Control
   - Code: QC metrics, filtering
   - Biological interpretation of QC (markdown):
     * Are pass rates expected for this data type?
     * Do failed samples have biological meaning?
     * Red flags from biological perspective?

5. Analysis
   - Code: Statistical tests, transformations
   - Biological reasoning for each step (markdown):
     * Why this method for this question?
     * What biological assumption being tested?
     * Positive/negative controls?

6. Results
   - Code: Generate results
   - Biological sanity checks (markdown):
     * Do magnitudes make sense?
     * Do directions align with biology?
     * Any known biology violated?

7. Visualization
   - Code: Plots
   - Biological interpretation scaffolding (markdown):
     * What biological pattern does this show?
     * Is this expected or surprising?
     * What follow-up questions does this raise?

8. Preliminary Interpretation
   - Bioinformatician's biological assessment (markdown):
     * Main findings in biological terms
     * Caveats and limitations
     * Questions for biologist-commentator

9. Handoff to Expert (if needed)
   - Structured questions for biologist-commentator (markdown):
     * Specific results needing interpretation
     * Unexpected findings to validate
     * Biological mechanisms to explore

10. Export (code)
    - Save data, figures, session info

生物学合理性检查框架

接受结果前执行以下检查：

表达量／丰度检查

• 数量级是否合理？（log2FC > 10 值得怀疑）
• 方向是否符合已知生物学规律？（检查几个已知基因）
• 阳性对照的表现是否符合预期？
• 阴性对照是否没有信号？

结合生物学视角的统计检查

• 主要命中项是否包含已知生物学结果？（通过文献验证）
• 结果对阈值变化是否稳健？
• 是否区分了批次效应和真实的生物学信号？
• 多重检验是否符合生物学研究的需要？（发现研究还是验证研究）

基因组学专项检查

• 染色体命名是否一致？（chr1 与 1）
• 坐标是否合理？（在染色体范围内）
• 基因特征的链方向是否正确？
• 整个分析中基因组版本是否一致？

实验设计

• 样本量是否足以支持该效应量？
• 重复是生物学重复还是技术重复？
• 是否已识别并处理混杂因素？
• 对于此类实验，所用对照是否合适？

如果任何一项检查未通过：在笔记本中记录，并标记以供生物学评论员审核

生物学背景模板

可直接粘贴到笔记本中的 Markdown 模板位于 assets/output-templates.md：

• 差异表达分析 — 生物学背景 + 合理性检查 + 初步解读 + 交接
• 单细胞聚类 — 生物学背景 + 聚类验证 + 交接
• 专家交接格式 — 精简的升级处理格式（含完整示例）

使用这些模板记录生物学背景并升级给生物学评论员（见下方工作流）。

生物学评论员集成模式

何时调用生物学评论员

分析前（方法验证）：

Skill(skill="biologist-commentator", args="Validate that DESeq2 appropriate for [specific experiment design]. Confirm controls adequate and confounders addressed.")

分析期间（快速检查）：

• 使用上述生物学合理性检查框架
• 记录任何警示信号
• 检查通过则继续，未通过则升级处理

分析后（专家解读）：

Skill(skill="biologist-commentator", args="Interpret biological significance of [specific finding]. Results show [X], which is [expected/unexpected]. Known biology suggests [Y]. Please validate interpretation and suggest mechanisms.")

交接工作流

1. 生物信息学家：运行分析、执行合理性检查并记录发现
2. 交接：在笔记本中创建结构化的交接部分（见上方模板）
3. 生物学评论员：提供专家解读、机制见解和验证
4. 生物信息学家：将解读纳入笔记本，并标记所需的验证工作

开始前检查清单

开始实施前，请确认：

• 分析计划明确规定了目标
• 数据文件存在且路径正确
• 已安装所需的软件包
• 已了解预期的输出格式
• 已设置随机种子以确保可复现性

完整清单请参阅 assets/analysis-checklist.md。

可复现性标准

至关重要：每项生物信息学分析都必须完全可复现。其他研究人员应能够重建你的计算环境并获得完全相同的结果。

环境文档（必需）

每个笔记本都应以环境文档开头。 模板（计算环境代码单元格、环境文件导出命令和笔记本 Markdown 单元格）：请参阅 assets/reproducibility-templates.md（“环境文档”）。

设置随机种子（随机过程必需）

在设置单元格中设置随机种子（numpy、random、scanpy、torch、tensorflow）。种子设置代码单元格和“随机操作” Markdown 模板：请参阅 assets/reproducibility-templates.md（“设置随机种子”）。

需要设置随机种子的生物信息学操作：

• 降维：UMAP、t-SNE、使用随机化 SVD 的 PCA
• 聚类：Leiden、Louvain（基于图）
• 抽样：随机子抽样、自助法、交叉验证
• 填补：随机填补方法
• 模拟：蒙特卡洛、置换检验
• 机器学习：随机森林、神经网络、k-means 初始化

会话信息输出（必需）

每个笔记本都应以完整的会话信息结尾。 会话信息代码单元格（包含单细胞和基础 Python 替代方案）：请参阅 assets/reproducibility-templates.md（“会话信息输出”）。

记录内容：

• Python 版本
• 操作系统
• 所有软件包版本（包括依赖项）
• 执行时间戳

这很重要，因为：

• 软件包版本之间的 API 可能发生变化
• 统计方法的实现会不断演进
• 错误会得到修复（结果可能随之改变）
• 审稿人需要验证所用方法

文件路径最佳实践

使用相对路径和变量，切勿硬编码绝对路径。 路径设置模板（笔记本顶部的路径变量）以及 BAD/GOOD 对比：请参阅 assets/reproducibility-templates.md（“文件路径最佳实践”）。

数据溯源文档

在笔记本中记录数据来源。 数据来源 Markdown 模板（输入数据 + 参考数据）：参见 assets/reproducibility-templates.md（“数据溯源文档”）。

这很重要，原因如下：

• 存储库中的数据可能会更新或被移除
• 基因组版本会影响基于坐标的分析
• 样本元数据有助于明确实验设计
• 让其他人能够下载完全相同的数据

可复现性预检清单

开始分析前，请确认：

• 已记录环境（存在 environment.yml 或 requirements.txt）
• 已在笔记本中记录环境创建方式
• 将为所有随机操作设置随机种子
• 文件路径使用变量（没有硬编码绝对路径）
• 已记录数据来源（下载地址、版本、日期）
• 已指定基因组版本 / 参考数据库版本
• 将在末尾添加会话信息单元格

移交给 PI 前，请确认：

• 笔记本可从头到尾运行且没有错误（重启内核并运行所有单元格）
• 结果可复现（运行两次，输出一致）
• 所有图表均以描述性名称保存到 FIGURES_DIR
• 所有处理后的数据均保存到 PROCESSED_DIR
• 会话信息单元格已执行，且输出可见
• 执行时间合理（常规分析少于 2 小时）

与 notebook-writer 技能集成

以编程方式创建笔记本时，请使用符合可复现性标准的 notebook-writer 技能。create_notebook_markdown 单元格列表模板：参见 assets/reproducibility-templates.md（“与 notebook-writer 技能集成”）。

常见的可复现性问题及修复方法

问题	原因	修复方法
重新运行后结果不同	未设置随机种子	为 numpy、random、scanpy、torch 设置随机种子
导入错误	缺少软件包版本信息	创建 requirements.txt 或 environment.yml
找不到文件	路径硬编码	使用在顶部定义的 Path 变量
软件包行为过时	软件包版本不匹配	使用 session_info.show() 记录版本
数据来源失效	URL 已更改或移除	记录下载日期、登录号和镜像站点
基因组坐标不匹配	基因组版本不同	在笔记本中指定版本（GRCh38 与 GRCh37）

生物信息学特有的可复现性注意事项

记录物种 / 参考版本、外部生物信息学工具，以及所有数据处理（QC / 过滤）参数。每项的模板（物种 / 参考代码单元格、外部工具 Markdown、QC_PARAMS 代码单元格）：参见 assets/reproducibility-templates.md（“生物信息学特有的可复现性注意事项”）。

代码质量标准

实现期间

• Copilot 会持续审查——请做好接受对抗性反馈的准备
• 编写清晰的注释，解释生物学背景
• 使用描述性变量名
• 将重复操作模块化为函数
• 为长时间运行的分析记录进度

测试

• 先使用小型测试数据进行验证
• 检查边界情况（空数据、单个样本、全为零）
• 与预期结果进行比较（阳性对照）
• 验证可复现性（运行两次，结果相同）

常见分析模式

模式 1：差异表达分析（RNA-seq）

# 1. Load counts
# 2. Filter low-abundance genes
# 3. Normalize (DESeq2, TMM, or library size)
# 4. Statistical test (DESeq2, edgeR, limma)
# 5. Multiple testing correction
# 6. Volcano plot + heatmap

→ 使用 pydeseq2 技能了解实现细节

模式 2：单细胞分析

# 1. Load AnnData object
# 2. QC filtering (cells and genes)
# 3. Normalization and log-transform
# 4. Feature selection (highly variable genes)
# 5. Dimensionality reduction (PCA, UMAP)
# 6. Clustering
# 7. Marker gene identification
# 8. Visualization

→ 使用 scanpy 技能了解实现细节

模式 3：序列分析

# 1. Read FASTA/FASTQ
# 2. Quality filtering
# 3. Alignment or motif search
# 4. Feature extraction
# 5. Statistical summary

→ 使用 biopython 技能了解实现细节

参考资料

如需可视化指导，请调用 plotting-advisor 技能——该技能涵盖图表类型选择、调色板选择（Okabe-Ito、viridis）、无障碍设计、反模式，以及符合 Tufte / Cleveland / Wong / Wilke 原则的领域特定惯例（火山图、UMAP、曼哈顿图、层次聚类热图、Kaplan-Meier、ROC、Bland-Altman）。

如需了解数据结构、分析工作流和统计方法选择，请直接查阅相关库技能（scientific-skills:scanpy、scientific-skills:pydeseq2、scientific-skills:biopython），或调用 statistician 技能来选择方法。

辅助脚本

scripts/ 中提供：

• qc_pipeline.py - RNA-seq 数据的自动化 QC
• differential_expression_template.py - 完整的 DESeq2 流程
• data_loader_helpers.py - 常见文件格式的函数

用法：将这些脚本作为参考实现来阅读，根据具体分析复制或调整，或在适当情况下通过 Bash 直接调用。

与领域技能集成

当分析需要专业知识时：

数据类型	主要技能	使用场景
单细胞 RNA-seq	scanpy	细胞类型识别、聚类、轨迹分析
Bulk RNA-seq	pydeseq2	差异基因表达分析
序列	biopython	比对、基序搜索、格式转换
统计建模	statsmodels	回归、时间序列、GLM
通路分析	gseapy 或手动处理	基因集富集分析

模式：

1. 使用 bioinformatician 处理整体工作流
2. 调用专用技能完成领域特定步骤
3. 将结果整合回主要分析中

Copilot 审查集成

在实现过程中，copilot 技能会审查你的代码：

• 预期会收到批判性反馈（有对抗性，但有建设性）
• 在继续之前立即修复问题
• 反复迭代，直到代码足够稳健
• 不要把批评放在心上——它能及早发现错误

交付内容

完整的笔记本应包含：

技术组件（现有）：

1. 代码单元格：注释完善、模块化的分析代码
2. 可视化：可用于发表的图表
3. 统计信息：完整报告（检验、p 值、效应量、n）
4. 导出内容：处理后的数据文件、图表文件
5. 会话信息：用于保证可复现性的包版本

生物学组件（新增）： 6. 生物学背景单元格（Markdown）：

• 用生物学术语描述研究问题
• 假设和预期结果
• 对各分析步骤的生物学描述
• 与生物学问题的相关性

7. 合理性检查文档（Markdown）：

   • 生物学合理性检查的结果
   • 阳性/阴性对照验证
   • 与已知生物学知识的比较
   • 警示信号或顾虑

8. 初步解读（Markdown）：

   • 用生物学语言描述主要发现
   • 与预期的一致性
   • 新颖或出乎意料的结果
   • 生物学意义

9. 专家交接部分（Markdown，如有需要）：

   • 提供给生物学评论者的结构化问题
   • 需要解读的具体发现
   • 建议的后续分析
   • 注意事项和局限性

质量指标：不会编写代码的生物学家也应能读懂笔记本

质量指标

满足以下条件时，Notebook 即可交付：

技术质量：

• 所有代码均可执行且无错误
• 已设置随机种子，结果可复现
• 已通过质量控制检查（阳性对照有效）
• 可视化图表标注规范
• 已完整报告统计结果
• Copilot 已批准代码（无尚未解决的严重问题）

生物学质量：

• 所有主要章节均提供了生物学背景（简洁，1-3 句）
• 已完成并记录生物学合理性检查
• 已根据生物学预期验证阳性/阴性对照
• 已用生物学术语撰写初步解读
• 若发现意外结果，已妥善安排交接给生物学评论人员
• 非编码背景的生物学家也能读懂 Notebook

集成就绪：

• PI 可据此扩展解读，用于发表
• 明确区分常规发现与需要专家审查的发现