biopython

Biopython：使用 Python 进行计算分子生物学

概述

Biopython 是一套全面且免费提供的 Python 生物计算工具。它提供序列操作、文件 I/O、数据库访问、结构生物信息学、系统发育学及许多其他生物信息学任务所需的功能。当前版本为 Biopython 1.87（于 2026 年 3 月 30 日发布）。它支持 Python 3.10-3.14 和 PyPy3.10，并依赖 NumPy。Biopython 1.87 还修复了解析不可信文件时 Bio.Entrez.Parser 中的 CVE-2025-68463，因此，对于需要解析外部提供的 Entrez XML 的工作流，建议使用 1.87 或更高版本。

何时使用此技能

在以下情况下使用此技能：

• 处理生物序列（DNA、RNA 或蛋白质）
• 读取、写入或转换生物文件格式（FASTA、GenBank、FASTQ、PDB、mmCIF 等）
• 通过 Entrez 访问 NCBI 数据库（GenBank、PubMed、Protein、Gene 等）
• 执行 BLAST 搜索或解析 BLAST 结果
• 进行序列比对（成对或多序列比对）
• 分析 PDB 文件中的蛋白质结构
• 创建、操作或可视化系统发育树
• 查找序列基序或分析基序模式
• 计算序列统计数据（GC 含量、分子量、熔解温度等）
• 执行结构生物信息学任务
• 处理群体遗传学数据
• 执行其他计算分子生物学任务

核心功能

Biopython 由多个模块化子包组成，分别针对特定的生物信息学领域：

1. 序列处理 - 使用 Bio.Seq 和 Bio.SeqIO 操作序列并进行文件 I/O
2. 比对分析 - 使用 Bio.Align 和 Bio.AlignIO 进行成对及多序列比对
3. 数据库访问 - 使用 Bio.Entrez 以编程方式访问 NCBI 数据库
4. BLAST 操作 - 使用 Bio.Blast 执行和解析 BLAST 搜索
5. 结构生物信息学 - 使用 Bio.PDB 处理三维蛋白质结构
6. 系统发育学 - 使用 Bio.Phylo 操作和可视化系统发育树
7. 高级功能 - 基序、群体遗传学、序列工具等

安装和设置

安装当前稳定版 Biopython，并指定明确的版本以确保可复现性：

uv pip install "biopython==1.87"

若要访问 NCBI 数据库，务必设置电子邮箱地址（NCBI 要求）。对于可复用的软件，请设置稳定的 Entrez.tool 值，并向 NCBI 注册工具和电子邮箱。若要获得更高的请求速率限制（10 req/s，而非 3 req/s），只从环境中读取 NCBI_API_KEY；不要将密钥硬编码，也不要加载无关的环境变量：

import os
from Bio import Entrez

Entrez.email = "[email protected]"  # required — use your real email
Entrez.tool = "your_tool_name"  # optional but recommended for reusable software

# Optional: register at https://www.ncbi.nlm.nih.gov/account/settings/
if api_key := os.environ.get("NCBI_API_KEY"):
    Entrez.api_key = api_key

使用此技能

详细信息、代码示例和参数表： references/using-this-skill.md。如果当前步骤适用，请阅读此文件。

通用工作流指南

阅读文档

当用户询问特定的 Biopython 任务时：

1. 根据任务描述确定相关模块
2. 使用 Read 工具阅读相应的参考文件
3. 提取相关代码模式，并根据用户的具体需求进行调整
4. 在任务需要时组合使用多个模块

参考文件的搜索模式示例：

# Find information about specific functions
rg -n "SeqIO.parse" references/sequence_io.md

# Find examples of specific tasks
rg -n "BLAST" references/blast.md

# Find information about specific concepts
rg -n "alignment" references/alignment.md

编写 Biopython 代码

编写 Biopython 代码时，请遵循以下原则：

1. 明确导入模块

   from Bio import SeqIO, Entrez
   from Bio.Seq import Seq
   

2. 使用 NCBI 数据库时设置 Entrez 电子邮箱；如果环境中存在 NCBI_API_KEY，则只读取该变量

   import os
   from Bio import Entrez
   
   Entrez.email = "[email protected]"
   Entrez.tool = "your_tool_name"
   if api_key := os.environ.get("NCBI_API_KEY"):
       Entrez.api_key = api_key
   

3. 使用合适的文件格式 - 检查哪种格式最适合任务

   # Common formats: "fasta", "genbank", "fastq", "clustal", "phylip"
   

4. 妥善处理文件 - 使用后关闭句柄，或使用上下文管理器

   with open("file.fasta") as handle:
       records = SeqIO.parse(handle, "fasta")
   

5. 处理大型文件时使用迭代器 - 避免将所有内容加载到内存中

   for record in SeqIO.parse("large_file.fasta", "fasta"):
       # Process one record at a time
   

6. 妥善处理错误 - 网络操作和文件解析都可能失败

   from urllib.error import HTTPError
   
   try:
       handle = Entrez.efetch(db="nucleotide", id=accession)
   except HTTPError as e:
       print(f"Error: {e}")
   

常见模式

模式 1：从 GenBank 获取序列

from Bio import Entrez, SeqIO

Entrez.email = "[email protected]"

# Fetch sequence
handle = Entrez.efetch(db="nucleotide", id="EU490707", rettype="gb", retmode="text")
record = SeqIO.read(handle, "genbank")
handle.close()

print(f"Description: {record.description}")
print(f"Sequence length: {len(record.seq)}")

模式 2：序列分析工作流

from Bio import SeqIO
from Bio.SeqUtils import gc_fraction

for record in SeqIO.parse("sequences.fasta", "fasta"):
    # Calculate statistics
    gc = gc_fraction(record.seq)
    length = len(record.seq)

    # Find ORFs, translate, etc.
    protein = record.seq.translate()

    print(f"{record.id}: {length} bp, GC={gc:.2%}")

模式 3：BLAST 并获取排名靠前的匹配结果

from Bio.Blast import NCBIWWW, NCBIXML
from Bio import Entrez, SeqIO

Entrez.email = "[email protected]"

# Run BLAST
result_handle = NCBIWWW.qblast("blastn", "nt", sequence)
blast_record = NCBIXML.read(result_handle)

# Get top hit accessions
accessions = [aln.accession for aln in blast_record.alignments[:5]]

# Fetch sequences
for acc in accessions:
    handle = Entrez.efetch(db="nucleotide", id=acc, rettype="fasta", retmode="text")
    record = SeqIO.read(handle, "fasta")
    handle.close()
    print(f">{record.description}")

模式 4：根据序列构建系统发育树

from Bio import AlignIO, Phylo
from Bio.Phylo.TreeConstruction import DistanceCalculator, DistanceTreeConstructor

# Read alignment
alignment = AlignIO.read("alignment.fasta", "fasta")

# Calculate distances
calculator = DistanceCalculator("identity")
dm = calculator.get_distance(alignment)

# Build tree
constructor = DistanceTreeConstructor()
tree = constructor.nj(dm)

# Visualize
Phylo.draw_ascii(tree)

最佳实践

1. 编写代码前，务必阅读相关参考文档
2. 使用 grep 在参考文件中搜索特定函数或示例
3. 解析前验证文件格式
4. 妥善处理缺失数据——并非所有记录都包含所有字段
5. 缓存下载的数据——不要重复下载相同的序列
6. 遵守 NCBI 速率限制——对于可复用的软件，请使用 API 密钥、已注册的工具名称 / 电子邮件值；对于大型任务，请使用 Entrez 历史记录和批处理
7. 处理大型文件前，先用小型数据集测试
8. 保持 Biopython 为最新版本，以获取最新功能和错误修复
9. 翻译时使用合适的遗传密码表
10. 记录分析参数，以确保可复现性

常见问题排查

问题：“No handlers could be found for logger 'Bio.Entrez'”

**解决方案：**这只是一个警告。设置 Entrez.email 即可消除。

问题：NCBI 返回“HTTP Error 400”

**解决方案：**检查 ID / 登录号是否有效且格式正确。

问题：解析文件时出现“ValueError: EOF”

**解决方案：**确认文件格式与指定的格式字符串一致。

问题：比对失败，提示“sequences are not the same length”

**解决方案：**使用 AlignIO 或 MultipleSeqAlignment 前，确保序列已完成比对。

问题：BLAST 搜索速度很慢

**解决方案：**大规模搜索时使用本地 BLAST，或缓存结果。

问题：PDB 解析器发出警告

**解决方案：**使用 PDBParser(QUIET=True) 屏蔽警告，或检查结构质量。

问题：Bio.HMM、Bio.MarkovModel 或 Bio.Application 导入失败

**解决方案：**这些模块已在 Biopython 1.86 中移除。HMM 请使用 hmmlearn，对于 CLI 包装器，请改用标准库中的 subprocess 模块，而不是 Bio.Application。

问题：升级到 1.86+ 后，PairwiseAligner 返回的比对结果变少

**解决方案：**在 1.86 中，默认 gap score 从 0 改为 -1，因此不再返回无意义的并列比对结果。如有需要，可设置 aligner.gap_score = 0 以恢复旧行为（参见 references/alignment.md）。

更多资源

• 官方文档：https://biopython.org/docs/latest/
• 教程：https://biopython.org/docs/latest/Tutorial/
• 示例集：https://biopython.org/docs/latest/Tutorial/（高级示例）
• GitHub：https://github.com/biopython/biopython
• 发行说明：https://github.com/biopython/biopython/blob/master/NEWS.rst
• 已弃用的 API：https://github.com/biopython/biopython/blob/master/DEPRECATED.rst
• 邮件列表：[email protected]

快速参考

要在参考文件中查找信息，请使用以下搜索模式：

# Search for specific functions
rg -n "function_name" references/*.md

# Find examples of specific tasks
rg -n "example" references/sequence_io.md

# Find all occurrences of a module
rg -n "Bio.Seq" references/*.md

总结

Biopython 为计算分子生物学提供了全面的工具。使用此技能时：

1. 确定任务领域（序列、比对、数据库、BLAST、结构、系统发育或高级功能）
2. 查阅 references/ 目录中的相应参考文件
3. 根据具体用例调整代码示例
4. 复杂工作流需要时，组合使用多个模块
5. 遵循文件处理、错误检查和数据管理方面的最佳实践

模块化的参考文档确保每项主要 Biopython 功能都有详细且可搜索的信息。

Agent 操作流程

1. 检查环境。 确认工具版本、参考基因组／注释版本以及输入格式（FASTQ、BAM、VCF、h5ad）。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会改变结果的值都应询问，不要猜测。
3. 先运行小规模版本。 先在小型子集（一个样本、一个染色体、几千个细胞）上运行流水线。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 解读结果前，检查 QC 指标、样本身份、基因组版本一致性和批次效应。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及哪些内容仍不确定。

如果出现以下情况	执行以下操作
输入之间的基因组版本或标识符不匹配	停止并协调一致（liftover、ID 映射）后再继续。
这些说明中提到的函数、标志或端点在已安装版本中缺失	查阅已安装版本自己的文档（help()、--help、官方文档），调整做法并告知用户。切勿捏造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明所作假设。

完整性规则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果某项内容无法运行或验证，请直言说明。
• 不要作出超出统计数据支持范围的生物学意义解读；报告多重检验校正。
• 此处与版本相关的细节可能已过时：请对照已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，请先征求同意。

相关技能

• scikit-bio：Python 生物序列和群落生态分析库 scikit-bio，适用于 DNA/RNA/蛋白质序列、pair_align 比对、系统发育…
• gget：通过 gget CLI 和 Python 包查询 20 多个生物信息学数据库和分析服务，涵盖 Ensembl 基因搜索、信息和…
• etetoolkit：使用 ETE 4 分析、操作、比较、注释和可视化系统发育树或其他层次树。