protein-sequence-similarity-search

前提条件

1. uv：uv のスキルを読み、セットアップの手順に従って、uv がインストールされ、PATH 上にあることを確認します。
2. ユーザーへの通知：ワークスペースのルートディレクトリに .licenses/protein_sequence_similarity_search_LICENSE.txt がまだ存在しない場合は、（1）https://www.ebi.ac.uk/jdispatcher/sss/ncbiblast および https://colabfold.com の利用条件を確認するようユーザーに目立つ形で通知し、次に（2）通知文とタイムスタンプを記録したファイルを作成します。
3. .env ファイル：ホームディレクトリに .env ファイルがあることを確認します。存在しない場合は作成します。
4. USER_EMAIL（任意ですが推奨）：EBI は BLAST ジョブの追跡に推奨していますが、このスキルは指定しなくても動作します。このスキルがユーザーのリクエストに関連すると思われる場合は、credentials スキルの安全な認証情報プロトコルを必ず使用して、この認証情報の有無を確認し、必要に応じてユーザーに提示を求めます。

目標

ユーザーが提供したアミノ酸配列（または .fasta ファイルのパス）を使い、利用可能な最速の方法で配列ホモログを検索し、上位ヒットの Markdown 形式の表を作成し、主要なアラインメント指標を解釈して、推定されるタンパク質機能を要約し、今後のプログラムによる解析に備えて結果をローカルに保存します。

基本ルール

• 厳密な検証：BLAST では、下の表に記載されているデータベースコードのみを使用します。
• 幻覚の禁止：スクリプトがエラーを出した場合、またはヒットがなかった場合は、ユーザーにはっきり伝えます。配列ホモログを捏造してはいけません。
• 出力ファイルを解析しない：JSON、a3m、その他の生出力ファイルを解析してはいけません。要約には、生成された .md ファイルを使用します。JSON やその他の出力は、後続のツールで使用するためのものです。
• 検索方法を必ず明記する：すべてのレポートで、検索に高速な MMseqs2（ColabFold API）を使用したか、低速な EBI BLAST を使用したかを明確に示します。
• 通知：このスキルを使用した場合は、その旨を出力に記載します。使用したプログラム（MMSEQS2 または EBI BLAST）と配列データベースを明示します。

検索方法の選択

ユーザーのリクエストに基づいて検索方法を選択します。

ユーザーが「quick search」または「fast search」と言った場合、特定の方法を指定していない場合／一般的なホモログ検索の場合、または判断できない場合は、mmseqs2_search.py を使用して MMseqs2（高速、デフォルト）を実行します。

MMseqs2 が失敗した場合（終了コード 2：RATELIMIT または API エラー）、ユーザーが「BLAST」を明示的にリクエストした場合、または特定の BLAST データベース（例：uniprotkb_swissprot、pdb、uniprotkb_human）を指定した場合は、uniprot_blast.py を使用して BLAST を実行します。

手順

1. ユーザーからのクエリを特定します。生の配列文字列（例：「MKVLY...」）またはローカルファイルへのパス（例：「./data/sequence.fasta」）を指定できます。

2. 上記のリストを使用して、検索方法を決定します。

パス A：MMseqs2 検索（デフォルト）

1. **ファイル名を生成する：**入力に基づいて、内容が分かる出力ファイル名を生成します（例：proteinA_mmseqs2.json および proteinA_mmseqs2.md）。

2. MMseqs2 スクリプトを実行します。

   • デフォルト：

   uv run scripts/mmseqs2_search.py <SEQUENCE_OR_FILE> -o <generated-filename.md> -j <generated-filename.json>
   

   • mgnify を含める場合：

   uv run scripts/mmseqs2_search.py <SEQUENCE_OR_FILE> -o <generated-filename.md> -j <generated-filename.json> --include-mgnify
   

3. スクリプトは ColabFold MMseqs2 API にクエリを送信し、完了するまでポーリングします。通常は高速で、2 分以内に完了します。

4. スクリプトがコード 2 で終了した場合（API 障害、レート制限）は、BLAST（以下のパス B）に自動的にフォールバックします。ユーザーには「MMseqs2 search failed, falling back to BLAST.」と伝えます。

5. **結果を読む：**生成された .md ファイルを開いて読みます。

パス B：BLAST 検索（明示的な指定またはフォールバック）

1. データベースの選択と検証： ユーザーのプロンプトに基づいて、最も適切なデータベースを選択します。

   • 以下の利用可能な BLAST データベース表を参照します。
   • ユーザーが分類群を指定した場合（例：「微生物で相同配列を検索」）、対応するDatabase Code（例：uniprotkb_bacteria）を選択します。
   • ユーザーがキュレーション済みのヒットを明示的に要求した場合は、uniprotkb_swissprotを使用します。
   • 特定のデータベースが要求されていない場合は、--databasesを指定しないでください。
   • 検証： データベースコードが表の項目と完全に一致していることを確認します。ユーザーがリストにないデータベースを要求した場合は、処理を進めず、使用可能なリストを提示してください。

2. ファイル名を生成：（例：proteinA_ebi_blast.json、proteinA_ebi_blast.md）。

3. この API では、リクエストヘッダーに含めるユーザーのメールアドレスを USER_EMAIL 環境変数に設定する必要があります。このスキルがユーザーのリクエストに関連すると考えられる場合は、credentialsスキルの安全な認証情報プロトコルを必ず使用して、この認証情報の有無を確認し、必要に応じて要求してください。

4. BLAST スクリプトを実行します。

   • デフォルト（uniprotkb）：

   uv run scripts/uniprot_blast.py <SEQUENCE_OR_FILE> -o <generated-filename.md> -j <generated-filename.json>
   

   • カスタムデータベース：

   uv run scripts/uniprot_blast.py <SEQUENCE_OR_FILE> -o <generated-filename.md> -j <generated-filename.json> --databases <db1,db2>
   

5. スクリプトは EBI BLAST API にクエリを送信し、サーバーをポーリングします。注： 最大 15 分かかる場合があります。完了までお待ちください。

6. 結果を読む： 生成された.mdファイルを開いて読みます。

共通の手順（どちらの方法でも）

1. 指標を解釈： 上位 3～5 件の配列相同体を要約します。以下を使用して一致の品質を評価します。
   • Q-Cov（クエリカバレッジ）： パーセンテージが高いほど、クエリ配列の大部分を一致がカバーしていることを示します。
   • E-value： E-value が低いほど（例：1e-50）、統計的有意性が非常に高いことを示します。
   • Seq Identity： 進化的背景を示します（高度に保存されているか、遠縁の相同体か）。
2. 機能分析を実施：
   • 結果の表にタンパク質の説明が含まれている場合は、説明を直接分析します。上位の相同体の具体的なタンパク質名と機能を報告し、見つかった機能、ドメイン、タンパク質ファミリーの多様性を要約します。
   • 結果に説明のない UniProt アクセッション ID しか含まれていない場合（MMseqs2 でよくあります）、要約する前に、uniprot-databaseスキルまたはその他の適切な方法を使って、上位 3～5 件のヒットのタンパク質名と機能を調べます。
3. 新たに作成された 2 つのファイル（.jsonと.md）とその保存場所をユーザーに伝えます。

利用可能なBLASTデータベース

• uniprotkb – UniProt Knowledgebase（UniProt KnowledgebaseにはUniProtKB/Swiss-ProtとUniProtKB/TrEMBLが含まれます）：UniProt Knowledgebase（UniProtKB）は、機能、分類、相互参照を含む、幅広くキュレーションされたタンパク質情報への中心的なアクセスポイントです。特定の配列について「既知のすべての情報」を取得するには、UniProtKBを検索してください
• uniprotkb_swissprot – UniProtKB/Swiss-Prot（UniProtKBの手動注釈セクション）：UniProt Knowledgebaseの手動キュレーションされたサブセクション
• uniprotkb_swissprotsv – UniProtKB/Swiss-Protアイソフォーム（UniProtKB/Swiss-Protの手動注釈済みアイソフォーム）：UniProt Knowledgebaseの手動キュレーションされたサブセクションに含まれるアイソフォーム配列
• uniprotkb_reference_proteomes – UniProtKB Reference Proteomes：UniProtKB Reference Proteomesの分類学的サブセット
• uniprotkb_trembl – UniProtKB/TrEMBL（UniProtKBの自動注釈セクション）：ENA Sequence（旧EMBL-Bank）のコーディング配列翻訳データから派生し、自動プロセスによって注釈が付与されたUniProt Knowledgebaseのサブセクション
• uniprotkb_refprotswissprot – UniProtKB Reference ProteomesとSwiss-Prot：UniProtKB Reference ProteomesとSwiss-Prot
• uniprotkb_archaea – UniProtKB Archaea：古細菌を対象とするUniProt Knowledgebaseの分類学的サブセット
• uniprotkb_arthropoda – UniProtKB Arthropoda：節足動物を対象とするUniProt Knowledgebaseの分類学的サブセット
• uniprotkb_bacteria – UniProtKB Bacteria：細菌を対象とするUniProt Knowledgebaseの分類学的サブセット
• uniprotkb_complete_microbial_proteomes – UniProtKB Complete Microbial Proteomes：完全な微生物プロテオームを対象とするUniProt Knowledgebaseの分類学的サブセット
• uniprotkb_eukaryota – UniProtKB Eukaryota：真核生物を対象とするUniProt Knowledgebaseの分類学的サブセット
• uniprotkb_fungi – UniProtKB Fungi：菌類を対象とするUniProt Knowledgebaseの分類学的サブセット
• uniprotkb_human – UniProtKB Human：ヒトを対象とするUniProt Knowledgebaseの分類学的サブセット
• uniprotkb_mammals – UniProtKB Mammals：哺乳類を対象とするUniProt Knowledgebaseの分類学的サブセット
• uniprotkb_nematoda – UniProtKB Nematoda：線虫を対象とするUniProt Knowledgebaseの分類学的サブセット
• uniprotkb_rodents – UniProtKB Rodents：げっ歯類を対象とするUniProt Knowledgebaseの分類学的サブセット
• uniprotkb_vertebrates – UniProtKB Vertebrates：脊椎動物を対象とするUniProt Knowledgebaseの分類学的サブセット
• uniprotkb_viridiplantae – UniProtKB Viridiplantae：緑色植物を対象とするUniProt Knowledgebaseの分類学的サブセット
• uniprotkb_viruses – UniProtKB Viruses：ウイルスを対象とするUniProt Knowledgebaseの分類学的サブセット
• uniprotkb_enzyme – UniProtKB Enzyme：酵素を対象とするUniProt Knowledgebaseの分類学的サブセット
• uniprotkb_covid19 – UniProtKB COVID-19：COVID-19を対象とするUniProt Knowledgebaseの分類学的サブセット
• uniref100 – UniProt Clusters 100%（UniRef100）：配列が100%同一のものを含むUniProt Reference Clusters（UniRef）
• uniref90 – UniProt Clusters 90%（UniRef90）：配列が90%同一のものを含むUniProt Reference Clusters（UniRef）
• uniref50 – UniProt Clusters 50%（UniRef50）：配列が50%同一のものを含むUniProt Reference Clusters（UniRef）
• pdb – タンパク質構造配列（PDBeタンパク質構造配列）：Brookhaven Protein Data Bank（PDB）に記載された構造由来のタンパク質配列