MSA Structure Prediction Pipeline

MSA结构预测流程

Predict protein structures with high accuracy by chaining two BioNeMo NIMs:

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

通过串联两个BioNeMo NIM，高精度预测蛋白质结构：

Step 1: MSA-Search  →  Step 2: OpenFold3
(搜索同源序列)       (借助MSA预测结构)

Overview

概述

Why chain these NIMs?

MSA-Search finds evolutionary homologs in UniRef30 and ColabFold databases using GPU-accelerated MMSeqs2. The resulting alignment provides crucial evolutionary information.
OpenFold3 uses the MSA to improve structure prediction accuracy — especially for sequences where no close homolog exists in PDB.
Running MSA-Search first means OpenFold3 gets the full evolutionary context rather than a single-sequence prediction.

为何要串联这些NIM？

MSA-Search利用GPU加速的MMSeqs2在UniRef30和ColabFold数据库中查找进化同源序列。生成的比对结果提供了关键的进化信息。
OpenFold3使用MSA提升结构预测精度——尤其适用于PDB中无近缘同源序列的情况。
先运行MSA-Search可让OpenFold3获取完整的进化上下文，而非仅基于单序列进行预测。

Before you start

开始前准备

Confirm with the user:

Query sequence: amino acid sequence to predict
MSA depth: how many sequences to retrieve (default 500; more = slower but more context)
API mode: hosted or local Docker?

Note: local MSA-Search requires 1.4 TB of database storage — strongly recommend hosted unless the user has that infrastructure.

For local Docker, do not assume MSA-Search and OpenFold3 are both on

localhost:8000

concurrently. Run one container at a time and hand off the A3M file, or start each NIM on a distinct host port and set the URLs explicitly.

与用户确认以下信息：

查询序列：待预测的氨基酸序列
MSA深度：要检索的序列数量（默认500；数量越多速度越慢，但上下文信息越丰富）
API模式：托管版还是本地Docker版？

注意：本地MSA-Search需要1.4TB的数据库存储空间——除非用户具备相应基础设施，否则强烈推荐使用托管版。

对于本地Docker版，请勿假设MSA-Search和OpenFold3会同时运行在

localhost:8000

。请一次运行一个容器并传递A3M文件，或在不同主机端口启动每个NIM并明确设置URL。

Step 1: Search for MSA with MSA-Search

步骤1：通过MSA-Search搜索MSA

python

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()

python

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")

---

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

---

Step 2: Predict structure with OpenFold3

步骤2：通过OpenFold3预测结构

Pass the MSA directly into OpenFold3's

msa

field:

python

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

将MSA直接传入OpenFold3的

msa

字段：

python

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}")

---

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}")

---

Comparing single-sequence vs MSA-informed prediction

单序列预测与基于MSA的预测对比

If the user wants to see the impact of MSA, run OpenFold3 twice — once with the full MSA and once with just the query sequence as a minimal alignment:

python

undefined

如果用户想了解MSA的影响，请运行两次OpenFold3——一次使用完整MSA，一次仅使用查询序列作为最小比对：

python

undefined

Minimal MSA (single sequence — same as no MSA context):

minimal_msa = { "main": { "a3m": { "alignment": f">query\n{query_sequence}", "format": "a3m" } } }


A larger, higher-quality MSA typically yields higher pLDDT and lower pDE, especially for proteins with many known homologs.

---

minimal_msa = { "main": { "a3m": { "alignment": f">query\n{query_sequence}", "format": "a3m" } } }


通常，规模更大、质量更高的MSA会带来更高的pLDDT和更低的pDE，尤其对于拥有大量已知同源序列的蛋白质。

---

For protein complexes

针对蛋白质复合物的处理

Use the

/paired/predict

endpoint of MSA-Search to get paired alignments for multi-chain complexes, then pass each chain's alignment into the corresponding molecule's

msa

field and

paired_msa

fields:

python

undefined

使用MSA-Search的

/paired/predict

端点获取多链复合物的配对比对结果，然后将每条链的比对结果传入对应分子的

msa

字段和

paired_msa

字段：

python

undefined

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_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, }

---

Quick reference — skill dependencies

快速参考——技能依赖项

Step	Skill	Key endpoint
MSA search	`msa-search-nim`	`/biology/colabfold/msa-search/predict`
Structure prediction	`openfold3-nim`	`/biology/openfold/openfold3/predict`

步骤	技能	关键端点
MSA搜索	`msa-search-nim`	`/biology/colabfold/msa-search/predict`
结构预测	`openfold3-nim`	`/biology/openfold/openfold3/predict`

msa-structure-prediction-pipeline

Original

Translation

MSA Structure Prediction Pipeline

MSA结构预测流程

Overview

概述

Before you start

开始前准备

Step 1: Search for MSA with MSA-Search

步骤1：通过MSA-Search搜索MSA

Extract the A3M alignment

Extract the A3M alignment

Save for reference

Save for reference

Count sequences in alignment

Count sequences in alignment

Step 2: Predict structure with OpenFold3

步骤2：通过OpenFold3预测结构

Build the OpenFold3 MSA structure from the retrieved alignment

Build the OpenFold3 MSA structure from the retrieved alignment

Optionally also include colabfold_envdb alignment if requested

Optionally also include colabfold_envdb alignment if requested

env_alignment = msa_result["alignments"]["colabfold_envdb"]["a3m"]["alignment"]

env_alignment = msa_result["alignments"]["colabfold_envdb"]["a3m"]["alignment"]

msa_data["colabfold_env"] = {"a3m": {"alignment": env_alignment, "format": "a3m"}}

msa_data["colabfold_env"] = {"a3m": {"alignment": env_alignment, "format": "a3m"}}

Comparing single-sequence vs MSA-informed prediction

单序列预测与基于MSA的预测对比

Minimal MSA (single sequence — same as no MSA context):

Minimal MSA (single sequence — same as no MSA context):

For protein complexes

针对蛋白质复合物的处理

Paired MSA search endpoint for complexes:

Paired MSA search endpoint for complexes:

Quick reference — skill dependencies

快速参考——技能依赖项