msa-structure-prediction-pipeline

MSA 構造予測パイプライン

2 つの BioNeMo NIM を連携させて、高精度でタンパク質構造を予測します。

Step 1: MSA-Search  →  Step 2: OpenFold3
(Search homologs)       (Predict structure with MSA)

---

概要

これらの NIM を連携させる理由：

• MSA-Search は、GPU で高速化された MMSeqs2 を使用して、UniRef30 および ColabFold データベースから進化的相同配列を検索します。得られたアラインメントは、重要な進化情報を提供します。
• OpenFold3 は MSA を使用して構造予測の精度を高めます。特に、PDB に近縁な相同配列が存在しない配列で効果を発揮します。
• 先に MSA-Search を実行することで、OpenFold3 は単一配列の予測ではなく、進化的背景の全体を活用できます。

---

始める前に

ユーザーに次の項目を確認してください：

1. クエリ配列：予測するアミノ酸配列
2. MSA の深さ：取得する配列数（デフォルトは 500。数が多いほど遅くなりますが、より多くの情報を得られます）
3. API モード：ホスト型ですか、それともローカル Docker ですか？

注：ローカルの MSA-Search には 1.4 TB のデータベースストレージが必要です。そのインフラストラクチャがない場合は、ホスト型を強くおすすめします。

ローカル Docker を使用する場合、MSA-Search と OpenFold3 の両方が同時に localhost:8000 で稼働していると想定しないでください。コンテナを一度に 1 つずつ実行して A3M ファイルを引き渡すか、各 NIM を異なるホストポートで起動し、URL を明示的に設定してください。

---

ステップ 1：MSA-Search で MSA を検索する

import requests, json, os
from pathlib import Path

NGC_API_KEY = os.getenv("NGC_API_KEY")
HOSTED = True

query_sequence = "<YOUR_PROTEIN_SEQUENCE>"

if HOSTED:
    msa_url = "https://health.api.nvidia.com/v1/biology/colabfold/msa-search/predict"
    headers = {"Content-Type": "application/json",
               "Authorization": f"Bearer {NGC_API_KEY}"}
else:
    msa_url = "http://localhost:8000/biology/colabfold/msa-search/predict"
    headers = {"Content-Type": "application/json"}

payload = {
    "sequence": query_sequence,
    "databases": ["Uniref30_2302", "colabfold_envdb_202108"],
    "e_value": 0.0001,
    "output_alignment_formats": ["a3m"],
}

r = requests.post(msa_url, headers=headers, json=payload)
r.raise_for_status()
msa_result = r.json()

# Extract the A3M alignment
a3m_alignment = msa_result["alignments"]["Uniref30_2302"]["a3m"]["alignment"]

# Save for reference
with open("query_msa.a3m", "w") as f:
    f.write(a3m_alignment)

# Count sequences in alignment
n_seqs = a3m_alignment.count(">")
print(f"Step 1 complete: found {n_seqs} homologous sequences")
print(f"MSA saved to query_msa.a3m")

---

ステップ 2：OpenFold3 で構造を予測する

MSA を OpenFold3 の msa フィールドに直接渡します。

if HOSTED:
    of3_url = "https://health.api.nvidia.com/v1/biology/openfold/openfold3/predict"
else:
    of3_url = "http://localhost:8000/biology/openfold/openfold3/predict"

# Build the OpenFold3 MSA structure from the retrieved alignment
msa_data = {
    "uniref30": {
        "a3m": {
            "alignment": a3m_alignment,
            "format": "a3m"
        }
    }
}

# Optionally also include colabfold_envdb alignment if requested
# env_alignment = msa_result["alignments"]["colabfold_envdb"]["a3m"]["alignment"]
# msa_data["colabfold_env"] = {"a3m": {"alignment": env_alignment, "format": "a3m"}}

payload = {
    "inputs": [{
        "input_id": "prediction_with_msa",
        "output_format": "pdb",
        "molecules": [
            {
                "type": "protein",
                "sequence": query_sequence,
                "diffusion_samples": 1,
                "msa": msa_data
            }
        ]
    }]
}

r = requests.post(of3_url, headers=headers, json=payload, timeout=300)
r.raise_for_status()
result = r.json()

output = result["outputs"][0]
for i, sample in enumerate(output["structures_with_scores"]):
    fmt = sample["format"]
    filename = f"predicted_structure_{i+1}.{fmt}"
    with open(filename, "w") as f:
        f.write(sample["structure"])
    print(f"\nStep 2 complete: {filename} saved")
    print(f"  Confidence:  {sample['confidence_score']:.4f}")
    print(f"  pLDDT:       {sample['complex_plddt_score']:.4f}")
    print(f"  pTM:         {sample['ptm_score']:.4f}")

---

単一配列による予測と MSA 情報を使用した予測の比較

MSA の効果を確認したい場合は、OpenFold3 を 2 回実行します。1 回目は完全な MSA を使用し、2 回目はクエリ配列のみを最小限のアラインメントとして使用します。

# Minimal MSA (single sequence — same as no MSA context):
minimal_msa = {
    "main": {
        "a3m": {
            "alignment": f">query\n{query_sequence}",
            "format": "a3m"
        }
    }
}

より大きく高品質な MSA は、通常、pLDDT を高く、pDE を低くします。特に、既知の相同配列が多数あるタンパク質で効果的です。

---

タンパク質複合体の場合

MSA-Search の /paired/predict エンドポイントを使用して、複数鎖の複合体のペアワイズアラインメントを取得します。その後、各鎖のアラインメントを、対応する分子の msa フィールドと paired_msa フィールドに渡します。

# Paired MSA search endpoint for complexes:
msa_paired_url = "https://health.api.nvidia.com/v1/biology/colabfold/msa-search/paired/predict"
paired_payload = {
    "sequences": [chain_A_sequence, chain_B_sequence],
    "e_value": 0.0001,
}

---

クイックリファレンス — スキルの依存関係

ステップ	スキル	主要なエンドポイント
MSA 検索	msa-search-nim	/biology/colabfold/msa-search/predict
構造予測	openfold3-nim	/biology/openfold/openfold3/predict