biopython

Biopython：Python による計算分子生物学

概要

Biopython は、生物学的計算に利用できる包括的な Python ツール群です。配列操作、ファイルの入出力、データベースへのアクセス、構造バイオインフォマティクス、系統学など、さまざまなバイオインフォマティクスのタスクに対応する機能を提供します。現在のバージョンは 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 による配列操作とファイルの入出力
2. アラインメント解析 - Bio.Align と Bio.AlignIO によるペアワイズおよび多重配列アラインメント
3. データベースへのアクセス - Bio.Entrez による NCBI データベースへのプログラムからのアクセス
4. BLAST 操作 - Bio.Blast による BLAST 検索の実行と解析
5. 構造バイオインフォマティクス - Bio.PDB による 3D タンパク質構造の処理
6. 系統学 - Bio.Phylo による系統樹の操作と可視化
7. 高度な機能 - モチーフ、集団遺伝学、配列ユーティリティなど

インストールとセットアップ

再現性を確保するため、明示的にバージョンを指定して、Biopython の最新の安定版をインストールします：

uv pip install "biopython==1.87"

NCBI データベースにアクセスする場合は、必ずメールアドレスを設定してください（NCBI で必須です）。再利用可能なソフトウェアでは、安定した Entrez.tool の値を設定し、NCBI にツールとメールアドレスを登録してください。より高いリクエスト制限（3 req/s ではなく 10 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 の ImportError

解決策： これらのモジュールは Biopython 1.86 で削除されました。HMM には hmmlearn を使用し、Bio.Application の CLI ラッパーの代わりに標準ライブラリの subprocess モジュールを使用してください。

問題：1.86 以降にアップグレードすると PairwiseAligner が返すアラインメント数が減る

解決策： 1.86 ではデフォルトのギャップスコアが 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 の主要な機能すべてについて、詳細で検索しやすい情報を確認できます。

エージェントの作業手順

1. 環境を確認します。 ツールのバージョン、参照ゲノム／アノテーションのビルド、入力形式（FASTQ、BAM、VCF、h5ad）を確認します。
2. 入力を特定します。 データまたはユーザーに確認して、形式、識別子、パラメーターを確認します。結果を左右する値は推測せず、質問してください。
3. まず小規模なバージョンを実行します。 まず、少数のサブセット（サンプル1つ、染色体1つ、数千個の細胞）でパイプラインを実行します。
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 を使って、系統樹やその他の階層ツリーを分析、操作、比較、注釈付け、可視化します。