alterlab-bioservices

BioServices

概要

BioServicesは、約40のバイオインフォマティクス関連のWebサービスやデータベースにプログラムからアクセスできるPythonパッケージです。生物学的データの取得、データベース間クエリの実行、識別子のマッピング、配列の解析を行い、Pythonのワークフローに複数の生物学的リソースを統合できます。

古いスクリプトに影響する最近の変更点（bioservices 1.16.0で確認済み）：

• SOAP/WSDLのサポートは1.15で削除されました — 現在利用できるサービスはすべてRESTであり、 WSDLServiceクラスとその依存関係であるsudsは削除されました。
• PSICQUICとBioGRIDは1.14で削除されました。 タンパク質相互作用には、 STRINGクラス（1.14で追加）またはIntactComplexを使用してください。from bioservices import PSICQUIC はImportErrorを発生させます。
• UniProt.mapping()はUniProtのジョブの生ペイロードを返します — {source_id: [target_ids]}形式の辞書ではなく、 {"results": [{"from": ..., "to": ...}, ...], "failedIds": [...]}です。詳しくは下記の「識別子のマッピング」を参照してください。
• NCBIblastのメソッド名はスネークケースです（get_status、get_result、get_result_types、 wait）。以前のgetStatus／getResultというキャメルケース名は削除されました。1.16では、 EBIではなくNCBIに直接ジョブを送信するncbiblastapi.NCBIBlastAPIも追加されています。

このスキルを使用する場面

以下の場合にこのスキルを使用してください：

• UniProt、PDB、Pfamからタンパク質配列、アノテーション、構造を取得する
• KEGGまたはReactomeを介して代謝経路や遺伝子機能を解析する
• 化学情報を得るために化合物データベース（ChEBI、ChEMBL、PubChem）を検索する
• 異なる生物学的データベース間で識別子を変換する（KEGG↔UniProt、化合物ID）
• 配列相同性検索（BLAST、MUSCLEアラインメント）を実行する
• 遺伝子オントロジー用語（QuickGO、GOアノテーション）をクエリする
• タンパク質間相互作用データ（STRING、IntactComplex）にアクセスする
• ゲノムデータ（BioMart、ArrayExpress、ENA）をマイニングする
• 単一のワークフローで複数のバイオインフォマティクスリソースのデータを統合する

該当しないケース

ケース	代わりに使用
1件の遺伝子、構造、エンリッチメントを手早く検索する	alterlab-gget
配列／構造ファイルを解析する、またはEntrezを直接スクリプトから利用する	alterlab-biopython
独自のデータベースでローカルBLAST+／makeblastdb／DIAMONDを使用する	alterlab-blast
1つのデータベース（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にはaccession、gene_names、organism_name、lengthなど、UniProtの戻り値フィールド名を指定）
• retrieve()：さまざまな形式（json、txt、xml、rdf、gff、fasta）でタンパク質エントリーを取得します
• mapping()：IDマッピングジョブを送信し、結果のペイロードを返します

参照先：UniProt APIの詳細についてはreferences/services_reference.mdを参照してください。

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ウェブサービス／chembl_webresource_client、またはライブUniChem REST APIを直接利用）で取得します。KEGGからChEMBLへの対応付けに使えるbioservicesの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を呼び出してください。 EBIではなくNCBIに送信したジョブの場合、bioservices 1.16では、同じrun/get_status/get_resultの形式でfrom bioservices import NCBIBlastAPIを使用できます。

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を含む辞書を返します。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 スイートの一部です。