alterlab-ena

ENA Database

概要

European Nucleotide Archive（ENA）は、ヌクレオチド配列データと関連メタデータを包括的に公開しているリポジトリです。REST API と FTP を通じて、DNA/RNA 配列、リードの生データ、ゲノムアセンブリ、機能アノテーションにアクセスして検索し、ゲノミクスやバイオインフォマティクスのパイプラインで利用できます。

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

次のような場合に、このスキルを使用してください。

• アクセッション番号を指定して、ヌクレオチド配列またはシーケンスリードの生データを取得する
• メタデータの条件でサンプル、研究、アセンブリを検索する
• 解析用に FASTQ ファイルまたはゲノムアセンブリをダウンロードする
• 生物の分類情報を検索する
• 配列アノテーションや機能データにアクセスする
• ENA のデータをバイオインフォマティクスのパイプラインに統合する
• 関連データベースを対象に相互参照検索を行う
• FTP または Aspera 経由でデータセットを一括ダウンロードする

使用しない場面

場面	代わりに使用するもの
リードの生データではなく、処理済みの発現シリーズ（GSE/GSM、シリーズマトリックス）	alterlab-geo
NCBI Gene の遺伝子を中心としたアノテーション（シンボル、RefSeq、GO）	alterlab-gene-db
ゲノムアノテーション、VEP、オーソログ、または座標検索	alterlab-ensembl
カスタムデータベースに対して BLAST をローカルで実行する	alterlab-blast

主な機能

1. データの種類と構造

ENA では、階層型のオブジェクト種別でデータを管理しています。

研究／プロジェクト - 関連データをまとめ、公開日を管理します。研究は、アーカイブされたデータを引用する際の基本単位です。

サンプル - シーケンスライブラリの作製元となる生体試料の単位を表します。ほとんどのデータ種別を登録する前に、サンプルを登録する必要があります。

リードの生データ - 次の要素で構成されます。

• 実験：シーケンス方法、ライブラリ調製、装置の詳細に関するメタデータ
• ラン：単一のシーケンスランから得られたリードの生データを含むファイルへの参照

アセンブリ - 完成度の異なるゲノム、トランスクリプトーム、メタゲノム、またはメタトランスクリプトームのアセンブリです。

配列 - EMBL Nucleotide Sequence Database に格納されている、アセンブル済みおよびアノテーション済みの配列です。コーディング領域／非コーディング領域と機能アノテーションを含みます。

解析 - 配列データの計算解析によって得られた結果です。

分類レコード - 系統と階級を含む分類情報です。

2. プログラムからのアクセス

ENA は、データにアクセスするための複数の REST API を提供しています。各エンドポイントの詳細については、references/api_reference.md を参照してください。

主な API：

ENA Portal API - すべての ENA データ種別を対象にした高度な検索機能

• ドキュメント：https://www.ebi.ac.uk/ena/portal/api/doc
• 複雑なクエリやメタデータ検索に使用します

ENA Browser API - レコードとメタデータを直接取得します

• ドキュメント：https://www.ebi.ac.uk/ena/browser/api/doc
• アクセッション番号を指定して特定のレコードをダウンロードする際に使用します
• エンドポイントに応じて、XML（メタデータ）または FASTA／EMBL フラットファイル（配列）を返します

ENA Taxonomy REST API - 分類情報を検索します

• 系統、階級、関連する分類データにアクセスできます

ENA Cross Reference Service - 外部データベースの関連レコードにアクセスします

• エンドポイント：https://www.ebi.ac.uk/ena/xref/rest/

CRAM Reference Registry - 参照配列を取得します

• エンドポイント：https://www.ebi.ac.uk/ena/cram/
• MD5 または SHA1 のチェックサムで検索できます

レート制限：ENA では、プログラムからのアクセスは 1 秒あたり 50 リクエストまでに制限されています。上限を超えると、HTTP 429（Too Many Requests）が返されます。

3. データの検索と取得

ブラウザーからの検索：

• すべてのフィールドを対象にした全文検索
• 配列相同性検索（BLAST との統合）
• 関連レコードを探す相互参照検索
• Rulespace クエリビルダーを使用した高度な検索

プログラムからのクエリ：

• 大規模な高度検索には Portal API を使用します
• データ種別、日付範囲、分類、またはメタデータフィールドで絞り込みます
• 結果は、表形式のメタデータ要約または XML レコードとしてダウンロードできます

API クエリの例：

import requests

# Search for samples from a specific study
base_url = "https://www.ebi.ac.uk/ena/portal/api/search"
params = {
    "result": "sample",
    "query": "study_accession=PRJEB1234",
    "format": "json",
    "limit": 100
}

response = requests.get(base_url, params=params)
samples = response.json()

4. データ取得形式

メタデータ形式：

• XML（ENA ネイティブ形式）
• JSON（Portal API 経由）
• TSV/CSV（表形式の概要）

シーケンスデータ：

• FASTQ（生リード）
• BAM/CRAM（アラインメント済みリード）
• FASTA（アセンブル済みシーケンス）
• EMBL フラットファイル形式（アノテーション付きシーケンス）

ダウンロード方法：

• API から直接ダウンロード（小さいファイル）
• FTP による一括データ転送
• 大規模データセットの高速転送には Aspera
• 一括ダウンロード用の enaBrowserTools コマンドラインユーティリティ

5. 一般的なユースケース

アクセッション番号で生シーケンスリードを取得する：

# Get FASTQ download URLs via the Portal filereport endpoint
# (the Browser API xml/{accession} returns run METADATA, not file URLs).
accession = "ERR123456"
url = ("https://www.ebi.ac.uk/ena/portal/api/filereport"
       f"?accession={accession}&result=read_run"
       "&fields=run_accession,fastq_ftp,fastq_md5&format=tsv")
# Then fetch each ;-separated fastq_ftp URL over FTP/HTTPS.

研究に含まれるすべてのサンプルを検索する：

# Use Portal API to list samples
study_id = "PRJNA123456"
url = f"https://www.ebi.ac.uk/ena/portal/api/search?result=sample&query=study_accession={study_id}&format=tsv"

特定の生物のアセンブリを検索する：

# Search assemblies by taxonomy. tax_tree()/tax_eq() take a numeric NCBI taxon ID —
# tax_tree(Escherichia coli) returns HTTP 400. Resolve names via the taxonomy API first.
taxon_id = 562  # Escherichia coli
url = ("https://www.ebi.ac.uk/ena/portal/api/search?result=assembly"
       f"&query=tax_tree({taxon_id})&fields=accession,scientific_name&format=json")

分類学的系統を取得する：

# Query taxonomy API
taxon_id = "562"  # E. coli
url = f"https://www.ebi.ac.uk/ena/taxonomy/rest/tax-id/{taxon_id}"

6. 解析パイプラインとの統合

一括ダウンロードのパターン：

1. Portal API を使用して、条件に一致するアクセッション番号を検索します
2. 検索結果からファイル URL を抽出します
3. FTP または enaBrowserTools を使用してファイルをダウンロードします
4. パイプラインでダウンロードしたデータを処理します

BLAST との統合： EBI の NCBI BLAST サービス（REST/SOAP API）と統合し、ENA シーケンスに対するシーケンス類似性検索を行います。

7. ベストプラクティス

レート制限：

• HTTP 429 レスポンスを受信した場合は、指数バックオフを実装します
• 可能な場合はリクエストをバッチ処理し、50 req/sec の制限内に収めます
• API 呼び出しを繰り返す代わりに、大規模データセットには一括ダウンロードツールを使用します

データの引用：

• 公開時には必ず Study/Project アクセッション番号を引用します
• 使用した特定のサンプル、ラン、アセンブリのアクセッション番号を記載します

API レスポンスの処理：

• レスポンスを処理する前に HTTP ステータスコードを確認します
• XML レスポンスは適切な XML ライブラリ（正規表現ではなく）を使用して解析します
• 大規模な結果セットではページネーションを処理します

パフォーマンス：

• 大きなファイル（>100MB）のダウンロードには FTP/Aspera を使用します
• メタデータのみが必要な場合は、XML より TSV/JSON 形式を優先します
• 多数のレコードを処理する場合は、分類情報の検索結果をローカルにキャッシュします

リソース

このスキルには、ENA を使用するための詳細なリファレンスドキュメントが含まれています。

references/

api_reference.md — 以下を含む、API エンドポイントの包括的なドキュメント：

• Portal API および Browser API の詳細なパラメーター
• レスポンス形式の仕様
• 高度なクエリ構文と演算子
• フィルタリングおよび検索用のフィールド名
• 一般的な API パターンと例

複雑な API クエリの作成、API レスポンスのデバッグ、または特定のパラメーターの詳細が必要な場合に、このリファレンスを読み込みます。

スクリプト

scripts/query_ena.py — ENA Portal API 用の実行可能なヘルパー（キー不要）：

python scripts/query_ena.py search --result read_run \
    --query 'study_accession="PRJEB1787"' --fields run_accession,fastq_ftp --limit 5
python scripts/query_ena.py filereport ERR164407