alterlab-bioservices

BioServices

概述

BioServices 是一个 Python 软件包，提供对约 40 个生物信息学 Web 服务和数据库的编程访问。检索生物数据、执行跨数据库查询、映射标识符、分析序列，并在 Python 工作流中集成多种生物资源。

会导致旧脚本无法运行的近期变更（已根据 bioservices 1.16.0 验证）：

• 1.15 中移除了 SOAP/WSDL 支持——所有仍在使用的服务现在都使用 REST，WSDLService 类及其 suds 依赖也已移除。
• 1.14 中移除了 PSICQUIC 和 BioGRID。 要查询蛋白质相互作用，请使用 STRING 类（在 1.14 中添加）或 IntactComplex；from bioservices import PSICQUIC 会引发 ImportError。
• UniProt.mapping() 返回原始的 UniProt 作业负载——{"results": [{"from": ..., "to": ...}, ...], "failedIds": [...]}——而不是 {source_id: [target_ids]} 字典。请参见下文“标识符映射”。
• NCBIblast 方法使用 snake_case（get_status、get_result、get_result_types、wait）；旧的 getStatus/getResult camelCase 名称已移除。1.16 还新增了 ncbiblastapi.NCBIBlastAPI，它会直接向 NCBI 提交任务，而不是提交到 EBI。

何时使用此技能

适用于以下场景：

• 从 UniProt、PDB、Pfam 检索蛋白质序列、注释或结构
• 通过 KEGG 或 Reactome 分析代谢通路和基因功能
• 在化合物数据库（ChEBI、ChEMBL、PubChem）中搜索化学信息
• 在不同生物数据库之间转换标识符（KEGG↔UniProt、化合物 ID）
• 执行序列相似性搜索（BLAST、MUSCLE 比对）
• 查询基因本体术语（QuickGO、GO 注释）
• 访问蛋白质-蛋白质相互作用数据（STRING、IntactComplex）
• 挖掘基因组数据（BioMart、ArrayExpress、ENA）
• 在单个工作流中整合多个生物信息学资源的数据

不适用的场景

场景	改用
快速查询单个项目（一个基因、一种结构、一次富集分析）	alterlab-gget
解析序列/结构文件或直接编写 Entrez 脚本	alterlab-biopython
在自己的数据库上运行本地 BLAST+ / makeblastdb / DIAMOND	alterlab-blast
深入使用单个数据库（完整的 KEGG、UniProt 或 ChEMBL 功能集）	alterlab-kegg、alterlab-uniprot、alterlab-chembl
对检索到的结构进行化学信息学分析（描述符、指纹）	alterlab-rdkit

核心功能

1. 蛋白质分析

检索蛋白质信息、序列和功能注释：

from bioservices import UniProt

u = UniProt(verbose=False)

# Search for protein by name. frmt is one of xlsx/fasta/json/gff/tsv — "tab" was
# retired with the June-2022 UniProt API and now raises.
results = u.search("ZAP70_HUMAN", frmt="tsv", columns="accession,gene_names,organism_name")

# Retrieve FASTA sequence (frmt defaults to json)
sequence = u.retrieve("P43403", frmt="fasta")

# Map identifiers between databases -> {"results": [{"from": ..., "to": ...}], "failedIds": [...]}
job = u.mapping(fr="UniProtKB_AC-ID", to="KEGG", query="P43403")
kegg_ids = [r["to"] for r in job["results"]]

主要方法：

• search()：使用灵活的搜索词查询 UniProt（frmt="tsv"，columns 使用 UniProt 返回字段名称，例如 accession、gene_names、organism_name、length）
• retrieve()：以多种格式（json、txt、xml、rdf、gff、fasta）获取蛋白质条目
• mapping()：提交 ID 映射作业并返回其结果负载

参考：references/services_reference.md，查看完整的 UniProt API 详情。

2. 通路发现与分析

访问基因和生物体的 KEGG 通路信息：

from bioservices import KEGG

k = KEGG()
k.organism = "hsa"  # Set to human

# Search for organisms
k.lookfor_organism("droso")  # Find Drosophila species

# Find pathways by name
k.lookfor_pathway("B cell")  # Returns matching pathway IDs

# Get pathways containing specific genes
pathways = k.get_pathway_by_gene("7535", "hsa")  # ZAP70 gene

# Retrieve and parse pathway data
data = k.get("hsa04660")
parsed = k.parse(data)

# Extract pathway interactions
interactions = k.parse_kgml_pathway("hsa04660")
relations = interactions['relations']  # Protein-protein interactions

# Convert to Simple Interaction Format
sif_data = k.pathway2sif("hsa04660")

主要方法：

• lookfor_organism()、lookfor_pathway()：按名称搜索
• get_pathway_by_gene()：查找包含指定基因的通路
• parse_kgml_pathway()：提取结构化通路数据
• pathway2sif()：获取蛋白质相互作用网络

参考：references/workflow_patterns.md，查看完整的通路分析工作流。

3. 化合物数据库复合搜索

在多个数据库中搜索并交叉引用化合物：

from bioservices import KEGG

k = KEGG()

# Search compounds by name — the tab-separated result rows are "C11222\tGeldanamycin"
results = k.find("compound", "Geldanamycin")

# Get compound information with database links
compound_info = k.get("cpd:C11222")  # Includes ChEBI links

# Cross-reference KEGG compound → ChEBI (KEGG→ChEMBL has no direct API)
mapping = k.conv("chebi", "compound")
mapping["cpd:C11222"]   # -> 'chebi:5292'  (Geldanamycin)

常见工作流：

1. 在 KEGG 中按名称搜索化合物
2. 提取 KEGG 化合物 ID
3. 使用 KEGG.conv 进行 KEGG → ChEBI 映射（ChEBI ID 也嵌入在 KEGG 条目中）
4. 如果需要 ChEMBL ID，请通过单独的途径获取（ChEMBL Web 服务 / chembl_webresource_client，或直接使用在线 UniChem REST API）——bioservices 没有用于 KEGG → ChEMBL 的 UniChem 便捷方法

请参阅 references/identifier_mapping.md，了解完整的跨数据库映射指南。

4. 序列分析

运行 BLAST 搜索和序列比对：

from bioservices import NCBIblast

s = NCBIblast(verbose=False)

# Run BLASTP against UniProtKB via the EBI job service
jobid = s.run(
    program="blastp",
    sequence=protein_sequence,
    stype="protein",
    database="uniprotkb",
    email="[email protected]"  # a real address is required; jobs are killed without one
)

# Poll, then fetch. Method names are snake_case since the API refresh.
s.wait(jobid)                    # blocks until the job leaves RUNNING
status = s.get_status(jobid)     # RUNNING | FINISHED | ERROR | FAILURE | NOT_FOUND
results = s.get_result(jobid, "out")
print(s.get_result_types(jobid))  # what formats this job can return

BLAST 任务以异步方式运行——请先检查状态（或调用 wait），再获取结果。 对于提交到 NCBI 而非 EBI 的任务，bioservices 1.16 新增了 from bioservices import NCBIBlastAPI，其 run/get_status/get_result 结构相同。

5. 标识符映射

在不同生物数据库之间转换标识符：

from bioservices import UniProt, KEGG

# UniProt mapping (many database pairs supported)
u = UniProt()
job = u.mapping(
    fr="UniProtKB_AC-ID",  # Source database
    to="KEGG",              # Target database
    query="P43403"          # Identifier(s) to convert; a list is also accepted
)

# The payload is {"results": [{"from": ..., "to": ...}], "failedIds": [...]}.
# Collapse it yourself when you want a per-source-ID dict:
from collections import defaultdict

mapped = defaultdict(list)
for row in job["results"]:
    mapped[row["from"]].append(row["to"])

# KEGG gene ID -> UniProt. Non-UniProt sources may only map *to* UniProtKB,
# so "KEGG" -> "UniProtKB" is valid while "KEGG" -> "UniProtKB_AC-ID" is not.
kegg_to_uniprot = u.mapping(fr="KEGG", to="UniProtKB", query="hsa:7535")

# For compounds, map KEGG → ChEBI via KEGG.conv
# (KEGG → ChEMBL has no direct API; obtain ChEMBL IDs separately
#  via the ChEMBL web service / chembl_webresource_client or the
#  live UniChem REST API directly)
k = KEGG()
kegg_to_chebi = k.conv("chebi", "compound")
chebi_from_kegg = kegg_to_chebi["cpd:C11222"]  # -> 'chebi:5292'

支持的映射（UniProt）：

• UniProtKB ↔ KEGG
• UniProtKB ↔ Ensembl
• UniProtKB ↔ PDB
• UniProtKB ↔ RefSeq
• 以及更多（请参阅 references/identifier_mapping.md）

6. Gene Ontology 查询

访问 GO 术语和注释：

from bioservices import QuickGO

g = QuickGO(verbose=False)

# Retrieve GO term information (returns parsed JSON from the QuickGO REST API)
term_info = g.get_go_terms("GO:0003824")
ancestors = g.get_go_ancestors("GO:0003824")

# Annotations: the parameters follow the QuickGO REST API, not the old
# protein=/format= signature. geneProductId is prefixed, limit is capped at 100.
annotations = g.Annotation(
    geneProductId="UniProtKB:P43403",
    includeFields="goName",
    limit=100,
    page=1,
)
for row in annotations["results"][:5]:
    print(row["goId"], row["goName"], row["goAspect"])

Annotation 会返回包含 numberOfHits 和 results 的 dict；请逐页获取，而不是提高 limit（值大于 100 时会引发 TypeError）。

7. 蛋白质-蛋白质相互作用

PSICQUIC 和 BioGRID 已于 bioservices 1.14 中移除。请使用 STRING 服务（或使用 IntactComplex 获取精选复合物）：

from bioservices import STRING

s = STRING()

# Functional + physical partners of a protein
partners = s.get_interaction_partners("ZAP70", species=9606, limit=20)

# Interactions within a given set of proteins
network = s.get_interactions(["ZAP70", "CD247", "LCK"], species=9606)

for row in partners:
    print(row["preferredName_A"], row["preferredName_B"], row["score"])

network_type="physical" 将结果限制为物理复合物；required_score（0–1000）用于设置置信度下限。JSON 输出中的 STRING 分数范围为 0–1。

多服务集成工作流

BioServices 擅长组合多个服务，进行全面分析。常见集成模式：

完整的蛋白质分析流程

执行完整的蛋白质表征工作流：

python scripts/protein_analysis_workflow.py ZAP70_HUMAN [email protected]

此脚本演示：

1. 在 UniProt 中搜索蛋白质条目
2. 获取 FASTA 序列
3. 进行 BLAST 相似性搜索
4. 发现 KEGG 通路
5. 映射 STRING 相互作用

通路网络分析

分析某个生物体的所有通路：

python scripts/pathway_analysis.py hsa output_directory/

提取并分析：

• 生物体的所有通路 ID
• 每条通路的蛋白质-蛋白质相互作用
• 相互作用类型分布
• 导出为 CSV/SIF 格式

跨数据库化合物搜索

跨数据库映射化合物标识符：

python scripts/compound_cross_reference.py Geldanamycin

获取：

• KEGG 化合物 ID
• ChEBI 标识符
• ChEMBL 标识符
• 基本化合物属性

批量标识符转换

一次转换多个标识符：

python scripts/batch_id_converter.py input_ids.txt --from UniProtKB_AC-ID --to KEGG

最佳实践

输出格式处理

不同服务会返回各种格式的数据：

• XML：使用 BeautifulSoup 解析（大多数 SOAP 服务）
• 制表符分隔（TSV）：使用 Pandas DataFrame 处理表格数据
• 字典/JSON：直接使用 Python 操作
• FASTA：集成 BioPython 进行序列分析

速率限制和详细程度

控制 API 请求行为：

from bioservices import KEGG

k = KEGG(verbose=False)  # Suppress HTTP request details
k.TIMEOUT = 30  # Adjust timeout for slow connections

错误处理

使用 try-except 块封装服务调用：

try:
    results = u.search("ambiguous_query")
    if results:
        # Process results
        pass
except Exception as e:
    print(f"Search failed: {e}")

生物体代码

使用标准的生物体缩写：

• hsa：Homo sapiens（人类）
• mmu：Mus musculus（小鼠）
• dme：Drosophila melanogaster
• sce：Saccharomyces cerevisiae（酵母）

列出所有生物体：k.list("organism") 或 k.organismIds

与其他工具集成

BioServices 可与以下工具良好协作：

• BioPython：对获取的 FASTA 数据进行序列分析
• Pandas：表格数据处理
• PyMOL：3D 结构可视化（获取 PDB ID）
• NetworkX：通路相互作用网络分析
• Galaxy：为工作流平台创建自定义工具封装

资源

scripts/

展示完整工作流的可执行 Python 脚本：

• protein_analysis_workflow.py：端到端蛋白质表征
• pathway_analysis.py：KEGG 通路发现与网络提取
• compound_cross_reference.py：多数据库化合物搜索
• batch_id_converter.py：批量标识符映射工具

可直接运行这些脚本，也可根据特定用例进行调整。

references/

按需加载的详细文档：

• services_reference.md：包含所有 40 多项服务及其方法的完整列表
• workflow_patterns.md：详细的多步骤分析工作流
• identifier_mapping.md：跨数据库 ID 转换完整指南

使用特定服务或处理复杂集成任务时，请加载参考文档。

安装

uv pip install bioservices

依赖项会自动管理。本软件包已在 Python 3.9-3.12 上测试。

附加信息

如需详细的 API 文档和高级功能，请参阅：

• 官方文档：https://bioservices.readthedocs.io/
• 源代码：https://github.com/cokelaer/bioservices
• references/services_reference.md 中的特定服务参考文档

属于 AlterLab Academic Skills 套件。