tooluniverse-sequence-retrieval

生物学的配列の取得

適切な曖昧性解消とデータベース間の取り扱いにより、DNA、RNA、タンパク質の配列を取得します。

重要：ツールの呼び出しでは、必ず英語の用語を使用してください。元の言語の用語は、フォールバックとしてのみ試してください。回答はユーザーの言語で返してください。

推測せずに検索する：アクセッション番号や配列のバージョンを決して推測しないでください。必ずNCBIまたはENAから取得して確認してください。

ドメインに関する推論

配列品質の優先順位：RefSeq（NM_/NP_ = キュレーション済み）> RefSeq予測（XM_/XP_）> GenBank（登録者による提出）。ヒトの標準アイソフォームには、MANE Selectトランスクリプトを優先してください。バージョン番号を確認してください。バージョンが新しくなると、アノテーションが改善される場合があります。

ワークフロー

Phase 0: Clarify (if needed) → Phase 1: Disambiguate Gene/Organism → Phase 2: Search & Retrieve → Phase 3: Report

---

フェーズ 0：確認（必要な場合）

次の場合にのみ質問してください：遺伝子が複数の生物に存在する、配列の種類が不明確、または株の指定が重要。 次の場合は省略してください：特定のアクセッションが指定されている、対象の生物と遺伝子の組み合わせが明確、生物を指定した完全ゲノムのリクエスト。

---

フェーズ 1：遺伝子／生物の曖昧性解消

アクセッションの種類を判断するフローチャート

接頭辞	種類	使用先
NC_/NM_/NR_/NP_/XM_	RefSeq	NCBIのみ
U*/M*/K*/X*/CP*/NZ_	GenBank	NCBIまたはENA
EMBL形式	EMBL	ENAを優先

重要：RefSeqアクセッションでENAツールを試さないでください。404が返されます。

確認項目

• 生物を確認（学名）
• 遺伝子シンボル／名称を特定
• 配列の種類を判定（ゲノム／mRNA／タンパク質）
• ツール選択用にアクセッションの接頭辞を特定

---

フェーズ 2：データの取得（内部処理）

検索は内部で行ってください。検索プロセスを説明してはいけません。

# Search NCBI Nucleotide
result = tu.tools.NCBI_search_nucleotide(
    operation="search", organism=organism, gene=gene,
    strain=strain, keywords=keywords, seq_type=seq_type, limit=10
)

# Get accessions from UIDs
accessions = tu.tools.NCBI_fetch_accessions(operation="fetch_accession", uids=result["data"]["uids"])

# Retrieve sequence (FASTA or GenBank format)
sequence = tu.tools.NCBI_get_sequence(operation="fetch_sequence", accession=accession, format="fasta")

# ENA alternative (non-RefSeq accessions only)
entry = tu.tools.ena_get_entry(accession=accession)
fasta = tu.tools.ena_get_sequence_fasta(accession=accession)

フォールバックの順序

最初に試すもの	フォールバック	備考
NCBI_get_sequence	ENA（GenBank形式の場合）	NCBIを利用できない
ena_get_entry	NCBI_get_sequence	ENAにRefSeqがない
NCBI_search_nucleotide	より広いキーワードを試す	結果がない
NCBI_get_sequence / ena_get_sequence_fasta	dbfetch_fetch_entry (db="refseqn"/"ena_sequence")	NCBIとENAそれぞれの専用ツールがどちらも利用できない場合。dbfetchは同じ基盤レコードをミラーリングします

---

フェーズ 3：配列プロファイルの報告

配列プロファイルレポートとして提示してください。検索プロセスは表示しないでください。以下を含めます。

1. 検索の概要：クエリ、データベース、結果数
2. 主要な配列：アクセッション、種類（RefSeq／GenBank）、生物、株、長さ、分子、トポロジー、キュレーションレベル
3. 配列プレビュー：FASTAの先頭行（省略表示）
4. アノテーションの概要：CDS／tRNA／rRNA／調節領域のフィーチャー数（GenBank形式から取得）
5. 代替配列：関連性とキュレーションレベルの高い順に並べ、ENAとの互換性も記載
6. データベース間の参照：RefSeq、GenBank、ENA/EMBL、BioProject、BioSample
7. ダウンロード形式：FASTA（BLAST／アラインメント用）、GenBank（アノテーション用）

キュレーションレベル

レベル	接頭辞	説明
RefSeq Reference（最良）	NC_, NM_, NP_	NCBIによるキュレーション済み、ゴールドスタンダード
RefSeq Predicted	XM_, XP_, XR_	計算による予測
GenBank Validated	Various	登録者による提出、一部キュレーション済み
GenBank Direct	Various	直接提出
Third Party	TPA_	サードパーティによるアノテーション

---

推論フレームワーク

配列品質：GenBankよりRefSeqを優先してください。バージョン番号を確認してください。定義に「PREDICTED」と含まれる配列は、実験的に検証されていません。

アクセッションに関する指針：RefSeq = NCBI専用。GenBank = ENA/EMBLにもミラーリング。ヒトやモデル生物では、デフォルトでRefSeq mRNA（NM_）を使用してください。微生物のクエリには、最も完全なゲノムアセンブリを使用してください。

データベース間の照合：同じ配列でも異なるアクセッションが付与されている場合があります（例：大腸菌K-12のGenBank U00096 = RefSeq NC_000913）。利用可能な場合は、必ず両方を報告してください。GenBankとRefSeqの相違は通常、RefSeqのキュレーションにより提出時の誤りが修正されたことを示します。

統合に関する質問

1. 利用可能な中で最も品質の高いアクセッションは何ですか？
2. 他のデータベースに代替アクセッションはありますか？
3. アノテーションはどの程度充実していますか？
4. 配列は想定される生物種／株に由来していますか？
5. ユーザーの下流解析にはどのダウンロード形式が適していますか？

---

エラー処理

エラー	対応
"No search criteria provided"	生物種、遺伝子、またはキーワードを追加してください
"ENA 404 error"	RefSeq の可能性があります。NCBI のみを使用してください
"No results found"	検索範囲を広げ、スペルを確認し、同義語を試してください
"Sequence too large"	サイズを伝え、代わりにダウンロードリンクを提示してください

---

ツールリファレンス

NCBI ツール: NCBI_search_nucleotide（検索）、NCBI_fetch_accessions（UID→アクセッション）、NCBI_get_sequence（取得） ENA ツール（GenBank/EMBL のみ）: ena_get_entry（メタデータ）、ena_get_sequence_fasta（FASTA）、ena_get_entry_summary（概要）

---

検索パラメーターリファレンス

NCBI_search_nucleotide: operation="search"、organism（学名）、gene（シンボル）、strain、keywords、seq_type（complete_genome/mrna/refseq）、limit

NCBI_get_sequence: operation="fetch_sequence"、accession、format（fasta/genbank）

---

生物種全体の参照プロテオーム（UniProt）

上記のフェーズ 1～3 とは粒度が異なります。src/tooluniverse/data/uniprot_ref_tools.json の UniProtRef_search_proteomes／UniProtRef_get_proteome（API キー 不要）は、生物種レベルのプロテオームメタデータ（タンパク質の総数、 染色体／構成要素の内訳、ゲノムアクセッション）を返します。個々の配列は返しません。 これらのツールは、「種 X の参照 プロテオームは何で、どのくらいの規模か」という質問の場合に使用してください （たとえば、プロテオーム全体の解析の前や、上記のフェーズ 2 に渡す適切な ゲノムアセンブリアクセッションを見つける場合）。個々の遺伝子／転写産物の配列を取得する 用途ではありません。

ツール	解決する内容	主な出力
UniProtRef_search_proteomes	生物種名／分類群 ID -> 一致するプロテオーム ID	id（UPXXXXXXXXX）、organism、taxon_id、proteome_type（Reference/Non Reference）、protein_count
UniProtRef_get_proteome	1 つのプロテオーム ID -> 生物種／アセンブリの詳細全体	organism.scientific_name／taxon_id、components[]（name、protein_count、genome_accession）、total_protein_count

実際の呼び出し例（ライブで検証済み）：UniProtRef_search_proteomes {"query": "SARS-CoV-2"} -> 3 件の結果が返されます。UP000464024（proteome_type: "Reference proteome"、17 個のタンパク質）と、同じ生物種に対する 2 件の "Non Reference proteome"（5 個と 10 個のタンパク質）が含まれています。最初の結果が正規のものだと 思い込まず、必ず proteome_type を確認し、"Reference proteome" を優先してください。 UP000464024 を UniProtRef_get_proteome に渡すと、components: [{"name": "Segment", "protein_count": 17, "genome_accession": "MN908947"}]（SARS-CoV-2 の実際の 参照ゲノムアクセッション）と total_protein_count: 17 が確認できます。ヒト （UP000005640）と大腸菌 K-12（UP000000625）の場合も、get_proteome は 同様に染色体／プラスミドごとの構成要素の内訳を返します。

レジストリでの重複（ライブで検証済み）： UniProt_search_proteomes（ src/tooluniverse/data/uniprot_proteomes_tools.json 内。rest.uniprot.org/proteomes/search に直接アクセス）は、上記の UniProtRef_search_proteomes と同じ検索を行いますが、 別の古いツール実装です。その利点は、BUSCO 完全性、ゲノムアセンブリ、構成要素ごとの タンパク質数、引用文献一覧全体を含む詳細なレコードを 1 回の呼び出しで返すことです。 一方、UniProtRef_search_proteomes ではこの情報を得るために UniProtRef_get_proteome を 2 回目に呼び出す必要があります。organism_name: human、organism_name:escherichia coli、organism_name:mouse でライブ検証済みで、 いずれも入れ子構造のオブジェクト全体が 1 回で返されます。トリアージに ID または proteomeType だけが必要であれば、どちらのツールでも使えます。最初から詳細全体が 必要な場合は、UniProt_search_proteomes を優先し、後続の呼び出しを省略してください。

配列アーカイブとクラスタリング（UniParc、UniRef）

フェーズ1〜3や上記のプロテオームツールとはまた異なる、次のような質問に答えます。 「この完全一致する配列は過去に登録されたことがあるか、あるとすればいくつのアクセッションに紐づいているか」 「この配列とほぼ同一の配列には、ほかにどのようなものがあるか」

ツール	回答する質問	主なパラメーター
UniParc_search	遺伝子／生物種／キーワードで、UniParcのすべてのアーカイブエントリーを検索します	query（UniProtのクエリ構文。例："gene:EGFR AND organism_id:9606"）、size
UniParc_get_entry	すべてのデータベース読み込みを通じて、この完全一致する配列を指していたUniProtアクセッションすべてと、完全な配列を取得します	upi
UniRef_search_clusters	遺伝子／生物種／キーワードで、配列類似性クラスタを検索します	query、cluster_type（UniRef100/90/50）、size
UniRef_get_cluster	クラスタの詳細：メンバー数、代表配列、共通の分類群	cluster_id（例：UniRef90_P00533）

実例（ライブで検証済み、EGFR／ヒト）：UniParc_search {"query": "gene:EGFR AND organism_id:9606", "size": 3} -> 異なるUPIエントリーが3件見つかり、それぞれ異なるUniProtアクセッション（Q8NDU8.1、Q9BZS2.1、Q9UMG5.1）と異なるoldest_created日付が付いています。UniParcでは、どのUniProtアクセッションが登録したかにかかわらず、固有のアミノ酸配列文字列ごとに1つのエントリーとして扱います。そのため、同じ遺伝子名を共有していても、配列の異なるアイソフォームや断片にはそれぞれ別のUPIが付与されます。UniRef_get_cluster {"cluster_id": "UniRef90_P00533"} -> Boreoeutheria（共通祖先の分類群）にまたがる、実際の119メンバーからなるクラスタが見つかります。representative_member（1210 aaのEGFR_HUMAN）には、統合されたUniProtKBアクセッション（P00533、O00688など）が9件以上含まれます。seed_id（UniParc IDのUPI0005F3CCCC）とrepresentative_memberは、必ずしも同じ配列ではないことに注意してください。

質問が「この完全一致する配列を実際に共有しているUniProtアクセッションはどれか」（重複排除）ならUniParcを使用します。質問が「X％の同一性で、この配列に類似するものはほかにあるか」（MSA／系統発生解析への入力として種をまたいで関連タンパク質を探す場合や、プロテオーム全体の解析前に冗長性を減らす場合）ならUniRefを使用します。

細胞内局在の語彙（UniProt Locations）

UniProtLocations_search／UniProtLocations_get_locationは、ID（SL-XXXX）またはフリーテキスト検索により、UniProtの統制された細胞内局在の語彙（オルガネラ、膜、トポロジー、配向）を検索します。

実際に注意すべき点（ライブで検証済み）：よく使われる「plasma membrane」という用語では、UniProtの実際の用語は見つかりません。UniProtの統制語彙では、この局在は「Plasma membrane」ではなく「Cell membrane」（SL-0039）と呼ばれています。"plasma membrane"または"Plasma membrane"を検索すると、関連がわずかな結果のみが返されます（例：SL-0552「Rhabdomere membrane」。その定義に「plasma membrane」と記載されているだけで、用語自体ではありません）。日常的に使う生物学用語がUniProtの命名と一致すると決めつけず、より広くUniProtで使われている用語（"membrane"、"cell"）で検索して、結果を確認してください。これは実際に語彙が一致しない問題であり、検索の不具合ではありません。

サンプルメタデータ（EBI BioSamples）

BioSamples_search/BioSamples_search_by_filter/BioSamples_get_sample/ BioSamples_get_relationships/BioSamples_get_facets は、シーケンシング／オミクスの登録を支えるサンプルについて、EBI の 6,000 万件以上のサンプルメタデータアーカイブ（生物種、組織、疾患、実験コンテキスト）を検索します。これは配列そのものとは異なるレイヤーであり、実際のデータを取得するために ENA/SRA にアクセスする前に「条件 X に該当するサンプルが存在するか」を調べるのに役立ちます。

実際に確認された注意点： BioSamples_search に複数語のフレーズ（"EGFR lung adenocarcinoma"）を指定すると結果はゼロ件でしたが、単一語の "EGFR" ではすぐに実際のヒットが返りました。この検索では、検索エンジンのように複数のフリーテキスト語を暗黙的に AND で結合しません。キーワードは一度に 1 つ使うか、複数の実際の条件を組み合わせる必要がある場合は BioSamples_search_by_filter（構造化された attribute/value のペア。例：attribute="organism", value="Homo sapiens"）を使ってください。フィルターを適用する前に、get_facets を使って実際に存在する属性値を確認できます（実際に確認済み：幅広いテキストクエリに対して、例として 432,302 サンプルなど、実際のファセット件数が返されます）。

生物種の分類体系（EBI Taxonomy）

EBITaxonomy_get_by_id/get_by_scientific_name/search_by_name/suggest は、生物種名／ID（EBI がミラーしている NCBI Taxonomy）を解決し、系統、ランク、分類区分、遺伝暗号を取得します。一般名（「mouse」「fruit fly」）には search_by_name を、入力途中の部分一致には suggest を使ってください。すでに判明している正確な名前／IDには get_by_scientific_name/get_by_id を使います。実際に確認済み：Homo sapiens -> tax_id: "9606"、完全な系統文字列 "Eukaryota; Metazoa; Chordata; ... Hominidae; Homo;"。

ドメイン横断のクイック検索（BioThings Gateway）

BioThings_list_apis/BioThings_query/BioThings_get_entity/ BioThings_get_metadata は、1 つの Elasticsearch 形式のクエリインターフェースを通じて、BioThings がホストする約 50 の API（薬物間相互作用、遺伝子と疾患に関するテキストマイニング、PubMed からマイニングされた予測など）にアクセスできます。これは、この汎用ゲートウェイを使う前に、ToolUniverse にそのリソース専用のカバレッジがあるかどうかをすばやく確認するのに役立ちます（BioThings_list_apis の preferred_tooluniverse_tool フィールドで、より高機能な専用ツールがすでに存在するかどうかがわかります。存在する場合は、そちらを優先してください）。フィールド指定の BioThings_query を作成する前に BioThings_get_metadata を呼び出し、フィールド名が正しいことを確認してください。実際に確認済み：BioThings_get_entity {"api": "mondo", "entity_id": "MONDO:0010329"} は、祖先用語を含む実際の MONDO 疾患オントロジーレコードを返します。また、ddinter API をクエリすると、重症度を含む実際の薬物間相互作用のペアが返ります。これは、必要なリソースに専用ツールがまだ存在しない場合の、すばやく 1 回の呼び出しで済む選択肢として、tooluniverse-data-integration-analysis の複数データベースからエビデンスを収集するワークフローを補完します。

データベース間の ID 解決（Bioregistry、Identifiers.org、TogoID）

「システム A の ID を持っているとき、システム B で対応する ID は何か」を解決する、互いに重複する 3 つのレジストリです。共通の例（ヒト TP53）を使ってライブで検証済みです。NCBI Gene 7157 -> TogoID_convert {"ids": "7157", "source": "ncbigene", "target": "ensembl_gene"} -> 実在する ENSG00000141510。この Ensembl gene の HGNC ID 11998 は、Bioregistry_resolve_reference {"prefix": "hgnc", "identifier": "11998"} と IdentifiersOrg_resolve {"namespace": "hgnc", "local_id": "11998"} の両方で解決すると同じ genenames.org のレコードになり、2 つのレジストリが一致することを確認できます。

• Bioregistry（Bioregistry_resolve_reference／get_registry／get_prefix_mappings／search_registries）— 2600 以上のプレフィックスに対応し、識別子ごとに複数のプロバイダー URL（bioregistry.io、identifiers.org、n2t.net、bio2rdf、該当する場合は GenCC／INDRA などのリソース固有のリンク）と、プレフィックスのメタデータ（ID の正規表現パターン、ホームページ）を返します。データベースの正確なプレフィックスがわからない場合は、まず search_registries を使ってください。
• Identifiers.org（IdentifiersOrg_resolve／get_namespace／search_namespaces／list_namespaces）— 元祖 MIRIAM レジストリです。resolve は、完全な機関／プロバイダーのメタデータ（どの組織がリゾルバーを運営しているか、推奨プロバイダーと代替プロバイダー）を返します。この情報は Bioregistry の default リンクには表示されません。URL だけでなく、ある名前空間の標準リゾルバーを誰が運営しているかを知る必要がある場合に適しています。
• TogoID（TogoID_convert／list_datasets）— 3 つの中で唯一、ID の URL を返すだけでなく、117 種類のデータセット間で ID を実際に変換します。たとえば、NCBI Gene -> Ensembl Gene -> UniProt -> PDB を、それぞれ 1 回の呼び出しで変換できます。有効な source／target データセットタイプの文字列を取得するため、まず list_datasets を呼び出してください。

このスキルに専用ツール（上記の UniProt／UniParc／UniRef／EBI Taxonomy）が直接接続していない ID システム間をワークフローで移動する必要がある場合は、このツール群を使ってください。たとえば、バリアント解析スキルの Ensembl gene ID を、別のツールが必要とする NCBI Gene ID に変換する場合などです。

EBI dbfetch（1 つのインターフェースで複数のデータベースに対応）

dbfetch_fetch_entry（db、id、format）／dbfetch_fetch_batch（db、カンマ区切りの ids、format）／dbfetch_list_databases／dbfetch_list_formats — 1 つの統一された呼び出しで、EBI がホストする 16 のデータベース（uniprotkb、pdb、embl、ena_sequence、refseqp、refseqn、ensemblgene、ensembltranscript、interpro、medline、taxonomy、uniprot、chembl、afdb、imgtligm、hgnc）からアクセッションを指定して生レコードを取得します。また、fetch_batch を使うと、同じデータベースから複数のアクセッションを 1 回のリクエストで取得できます。API キーは不要です。ライブで検証済みです。dbfetch_fetch_entry {"db": "uniprotkb", "id": "P04637", "format": "fasta"} は、実在するヒト p53（P53_HUMAN）の FASTA 配列を返します。dbfetch_fetch_batch {"db": "uniprotkb", "ids": "P04637,P01308", "format": "fasta"} は、p53 とインスリンの両方を 1 回の応答で返します。

上記の専用ツールではなく、こちらを使う場合：データベースごとに異なるツール／クライアントを使い分けずに、異なる種類のデータベースから単発または一括で取得したい場合（たとえば、短いセッション中に UniProt、PDB、EMBL の各エントリーを取得する場合）、または fetch_batch の「複数アクセッションを 1 回の呼び出しで取得」する利便性が必要な場合は、dbfetch を使ってください。より豊富な構造化フィールド（相互参照、特徴アノテーション、キュレーションレベルのメタデータ）が必要な場合は、上記の専用ツール（UniProt／UniParc／ENA／NCBI）を優先してください。dbfetch が返すのはデータベース標準のフラットファイル／FASTA／XML テキストであり、解析済みの構造化オブジェクトではありません。