proteinmpnn

ProteinMPNN 序列设计

先决条件

要求	最低配置	推荐配置
Python	3.8+	3.10
CUDA	11.0+	11.7+
GPU 显存	8GB	16GB（T4）
RAM	8GB	16GB

运行方法

第一次使用？ 请参阅入门指南，设置 Modal 和 biomodals。

选项 1：本地安装（推荐）

git clone https://github.com/dauparas/ProteinMPNN.git
cd ProteinMPNN

python protein_mpnn_run.py \
  --pdb_path backbone.pdb \
  --out_folder output/ \
  --num_seq_per_target 16 \
  --sampling_temp "0.1"

GPU：T4（16GB）即可 | 耗时：约 50-100 条序列/分钟

选项 2：Modal（通过 LigandMPNN 封装器）

cd biomodals
# modal_ligandmpnn.py takes --input-pdb and forwards run.py args via --params-str
modal run modal_ligandmpnn.py \
  --input-pdb backbone.pdb \
  --params-str "--model_type protein_mpnn --number_of_batches 16 --temperature 0.1"

GPU（Modal）：默认 A10G | 超时：默认 900s

注意：LigandMPNN 包含 ProteinMPNN 功能（使用 --model_type protein_mpnn 选择）。

配置架构

核心参数

参数	默认值	范围	说明
--pdb_path	必填	路径	单个 PDB 输入
--pdb_path_chains	全部	A,B	要设计的链（逗号分隔）
--out_folder	必填	路径	输出目录
--num_seq_per_target	1	1-1000	每个结构的序列数
--sampling_temp	"0.1"	"0.0001-1.0"	温度（字符串！）
--seed	0	int	随机种子
--batch_size	1	1-32	批次大小

温度指南

0.1  -> Low diversity, high recovery (production)
0.2  -> Moderate diversity (default)
0.3  -> Higher diversity (exploration)
0.5+ -> Very diverse, lower quality

重要：温度必须以字符串而非浮点数传入。

常见错误

温度参数

✅ 正确：

--sampling_temp "0.1"    # String with quotes

❌ 错误：

--sampling_temp 0.1      # Float without quotes - may cause errors
--sampling_temp 0.1,0.2  # Multiple temps need proper format

固定位置 JSONL

✅ 正确：

{"A": [1, 2, 3, 10, 11], "B": [5, 6]}

❌ 错误：

{"A": "1,2,3,10,11"}     # String instead of list
{A: [1, 2, 3]}           # Missing quotes on key
{"A": [1,2,3,]}          # Trailing comma

链选择

✅ 正确：

--pdb_path_chains A,B    # No spaces

❌ 错误：

--pdb_path_chains A, B   # Space after comma
--pdb_path_chains "A,B"  # Quotes may cause issues

氨基酸偏置

# Bias toward certain AAs (positive = favor)
--bias_AA_jsonl '{"A": {"A": 1.5, "W": -2.0}}'

# Omit specific AAs globally
--omit_AAs "CM"  # No cysteine or methionine

# Per-position omission
--omit_AA_jsonl '{"A": {"1": "C", "2": "CM"}}'

多链设计

# Design chains A and B together
--pdb_path_chains A,B

# Tie chains (same sequence)
--tied_positions_jsonl tied.jsonl

变体比较

变体	用途	主要区别
ProteinMPNN	通用	原始模型
SolubleMPNN	表达	使用可溶性蛋白训练
LigandMPNN	小分子	感知配体的上下文

输出格式

output/
├── seqs/
│   └── backbone.fa          # FASTA sequences
└── backbone_pdb/
    └── backbone_0001.pdb    # PDBs with designed sequence

FASTA 标题格式

>backbone_0001, score=1.234, global_score=1.234, seq_recovery=0.85
MKTAYIAKQRQISFVKSHFSRQLE...

常见工作流

结合体序列设计

python protein_mpnn_run.py \
  --pdb_path binder_backbone.pdb \
  --out_folder output/ \
  --num_seq_per_target 16 \
  --sampling_temp "0.1" \
  --pdb_path_chains B  # Design binder chain only

界面重新设计

# Fix core, design interface
python protein_mpnn_run.py \
  --pdb_path complex.pdb \
  --fixed_positions_jsonl core_positions.jsonl \
  --num_seq_per_target 32

多状态设计

# Design for multiple conformations
python protein_mpnn_run.py \
  --pdb_path_multi state1.pdb,state2.pdb \
  --num_seq_per_target 16

输出示例

成功运行

$ python protein_mpnn_run.py --pdb_path backbone.pdb --out_folder output/ --num_seq_per_target 8
Loading model weights...
Designing sequences for backbone.pdb
Generated 8 sequences in 2.3 seconds

output/seqs/backbone.fa:
>backbone_0001, score=1.234, global_score=1.189, seq_recovery=0.82
MKTAYIAKQRQISFVKSHFSRQLEERGLTKE...
>backbone_0002, score=1.198, global_score=1.156, seq_recovery=0.79
MKTAYIAKQRQISFVKSQFSRQLDERGLTKE...

良好输出的特征：

• 分数：1.0-2.0（越低 = 越有信心）
• 序列恢复率：从头设计为 0.3-0.6，重新设计为 0.7-0.9
• 当 temp > 0.1 时，序列具有多样性（并非全部相同）

决策树

Should I use ProteinMPNN?
│
├─ Have a backbone structure?
│  ├─ Yes → Continue below
│  └─ No → Use RFdiffusion first
│
├─ What's in the binding site?
│  ├─ Nothing / protein only → ProteinMPNN ✓
│  ├─ Small molecule / ligand → Use LigandMPNN
│  └─ Metal / cofactor → Use LigandMPNN
│
├─ Priority?
│  ├─ Solubility/expression → Consider SolubleMPNN
│  ├─ Speed → ProteinMPNN ✓
│  └─ AF2 optimization → Consider ColabDesign
│
└─ Need fixed positions?
   ├─ Yes → Use --fixed_positions_jsonl
   └─ No → ProteinMPNN ✓ (design all)

典型性能

任务规模	耗时（T4）	成本（Modal）	备注
100 个骨架 × 8 条序列	15-20 分钟	~$2	标准
500 个骨架 × 8 条序列	1-1.5 小时	~$8	大型任务
1000 个骨架 × 16 条序列	3-4 小时	~$18	全面

吞吐量：在 T4 GPU 上约为 50-100 条序列/分钟。

---

验证

grep -c "^>" output/seqs/*.fa  # Should match backbone_count × num_seq_per_target

---

故障排除

序列多样性低：将 sampling_temp 提高到 0.2-0.3
恢复率低：将 sampling_temp 降低到 0.1
OOM 错误：减小 batch_size
出现不需要的半胱氨酸：使用 --omit_AAs "C"

错误解读

错误	原因	解决方法
RuntimeError: CUDA out of memory	蛋白质过长或批次过大	减小 batch_size 或使用更大的 GPU
KeyError: 'A'	PDB 中没有该链	检查 PDB 文件中的链 ID
JSONDecodeError	JSONL 格式无效	验证 JSON 语法（参见“常见错误”）
IndexError: list index	链或残基列表为空	检查 PDB 是否包含原子，而不只是 HEADER

---

下一步：进行结构预测以验证 → 使用 protein-qc 进行筛选。