msa-structure-prediction-pipeline

MSA 结构预测流水线

通过串联两个 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 上。请一次运行一个容器并传递 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：一次使用完整 MSA，另一次仅将查询序列作为最简比对：

# 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