alterlab-diffdock

DiffDock：基于扩散模型的分子对接

概述

DiffDock 是一种基于扩散的深度学习工具，用于分子对接，可预测小分子配体与蛋白质靶标的 3D 结合构象。此代码库的默认模型为 DiffDock-L（2024 年 2 月）；它广泛用于盲对接，不过协同折叠模型（Boltz-2、Chai-1）和基于物理的方法进行重评分如今也常用作补充，预测出的构象应检查其物理有效性（例如使用 PoseBusters）。

核心功能：

• 使用深度学习高精度预测配体结合构象
• 支持蛋白质结构（PDB 文件）或序列（通过 ESMFold）
• 处理单个复合物或批量虚拟筛选任务
• 生成置信度分数，用于评估预测可靠性
• 处理多种配体输入（SMILES、SDF、MOL2）

关键区别：DiffDock 预测的是结合构象（3D 结构）和置信度（预测确定性），而非结合亲和力（ΔG、Kd）。请务必结合评分函数（GNINA、MM/GBSA）评估亲和力。

何时使用此技能

在以下情况应使用此技能：

• “将此配体对接到蛋白质”或“预测结合构象”
• “运行分子对接”或“执行蛋白质-配体对接”
• “虚拟筛选”或“筛选化合物库”
• “这个分子会在哪里结合？”或“预测结合位点”
• 基于结构的药物设计或先导化合物优化任务
• 涉及 PDB 文件 + SMILES 字符串或配体结构的任务
• 对多个蛋白质-配体对进行批量对接

不会触发的情况

场景	改用
在云平台上计算结合亲和力 / 对接分数（AutoDock Vina）	alterlab-rowan
对复合物进行 MD 模拟，分析轨迹中的构象稳定性 / RMSD	alterlab-molecular-dynamics
预测蛋白质-蛋白质或蛋白质-核酸复合物结构	alterlab-boltz 或 alterlab-chai
仅预测未结合配体的蛋白质结构	alterlab-alphafold
查询该靶标已测定的蛋白质-配体亲和力	alterlab-bindingdb

安装与环境配置

检查环境状态

开始 DiffDock 任务前，请验证环境配置：

# Use the provided setup checker
python scripts/setup_check.py

此脚本会检查 Python 版本、带 CUDA 的 PyTorch、PyTorch Geometric、RDKit、ESM 及其他依赖项。

安装选项

选项 1：Conda（推荐）

git clone https://github.com/gcorso/DiffDock.git
cd DiffDock
conda env create --file environment.yml
conda activate diffdock

选项 2：Docker

docker pull rbgcsail/diffdock
docker run -it --gpus all --entrypoint /bin/bash rbgcsail/diffdock
micromamba activate diffdock

重要说明：

• 强烈建议使用 GPU（相比 CPU 可提速 10–100 倍）
• 首次运行时会预计算 SO(2)/SO(3) 查找表（约 2–5 分钟）
• 如果模型检查点（约 500 MB）不存在，系统会自动下载

核心工作流

工作流 1：单个蛋白质-配体对接

**适用场景：**将一个配体对接到一个蛋白质靶标

输入要求：

• 蛋白质：PDB 文件或氨基酸序列
• 配体：SMILES 字符串或结构文件（SDF/MOL2）

命令：

python -m inference \
  --config default_inference_args.yaml \
  --protein_path protein.pdb \
  --ligand "CC(=O)Oc1ccccc1C(=O)O" \
  --out_dir results/single_docking/

替代方式（蛋白质序列）：

python -m inference \
  --config default_inference_args.yaml \
  --protein_sequence "MSKGEELFTGVVPILVELDGDVNGHKF..." \
  --ligand ligand.sdf \
  --out_dir results/sequence_docking/

**输出结构：**DiffDock 会为每个复合物写入一个子目录（即使是单次运行也如此），置信度会嵌入每个构象的文件名中：

results/single_docking/
└── complex_0/
    ├── rank1.sdf                   # Top pose (no score in name)
    ├── rank1_confidence-0.42.sdf   # Same pose, confidence in filename
    ├── rank2_confidence-1.10.sdf   # 2nd-ranked pose
    ├── ...
    └── rank10_confidence-3.05.sdf  # 10th pose (default: 10 samples)

没有单独的 confidence_scores.txt；置信度值就是 confidenceN.NN 后缀。构象按置信度降序排列（rank1 = 最佳）。

工作流 2：批量处理多个复合物

使用场景： 将多个配体对接到蛋白质，开展虚拟筛选活动

步骤 1：准备批处理 CSV

使用提供的脚本创建或验证批处理输入：

# Create template
python scripts/prepare_batch_csv.py --create --output batch_input.csv

# Validate existing CSV
python scripts/prepare_batch_csv.py my_input.csv --validate

CSV 格式：

complex_name,protein_path,ligand_description,protein_sequence
complex1,protein1.pdb,CC(=O)Oc1ccccc1C(=O)O,
complex2,,COc1ccc(C#N)cc1,MSKGEELFT...
complex3,protein3.pdb,ligand3.sdf,

必需列：

• complex_name：唯一标识符
• protein_path：PDB 文件路径（使用序列时留空）
• ligand_description：SMILES 字符串或配体文件路径
• protein_sequence：氨基酸序列（使用 PDB 时留空）

步骤 2：运行批量对接

python -m inference \
  --config default_inference_args.yaml \
  --protein_ligand_csv batch_input.csv \
  --out_dir results/batch/ \
  --batch_size 10

大规模虚拟筛选（>100 个化合物）：

将每个蛋白质–配体对放入同一个 CSV，并运行一次 inference 调用。启动时， inference.py 会在一次批处理中计算 CSV 中所有复合物的 ESM2（esm2_t33_650M_UR50D）嵌入，并将其复用于置信度模型——无需单独的预计算步骤，推理时也无需使用 --esm_embeddings_path 标志。 （datasets/esm_embedding_preparation.py / esm_embeddings_to_pt.py 仅用于训练/评估基准。）如果担心 GPU 内存或运行时间，可将超大型库拆分为多个 CSV。

配置注意事项： --config YAML 中的值会在 CLI 标志应用之后生效，并覆盖这些标志。samples_per_complex、inference_steps 和 temp_* 参数位于 default_inference_args.yaml 中，因此同时传入 --samples_per_complex 20 和 --config default_inference_args.yaml 等配置不会生效——请改为编辑 YAML 文件副本（--batch_size 不在默认 YAML 中，因此 CLI 标志有效）。

工作流 3：分析结果

对接完成后，分析置信度分数并对预测结果排序：

# Analyze all results
python scripts/analyze_results.py results/batch/

# Show top 5 per complex
python scripts/analyze_results.py results/batch/ --top 5

# Filter by confidence threshold
python scripts/analyze_results.py results/batch/ --threshold 0.0

# Export to CSV
python scripts/analyze_results.py results/batch/ --export summary.csv

# Show top 20 predictions across all complexes
python scripts/analyze_results.py results/batch/ --best 20

分析脚本会：

• 解析所有预测结果的置信度分数
• 将结果分类为高（>0）、中（-1.5 至 0）或低（<-1.5）
• 对复合物内部及不同复合物之间的预测结果排序
• 生成统计摘要
• 将结果导出为 CSV，以供后续分析

置信度分数解读

了解分数：

分数范围	置信度等级	解读
> 0	高	预测可信度高，结果可能准确
-1.5 至 0	中	预测较为合理，需仔细验证
< -1.5	低	预测不确定，需验证

重要说明：

1. 置信度 ≠ 亲和力：置信度高表示模型对结构有较高把握，不代表结合能力强
2. 具体情况很重要：需根据以下情况调整预期：
   • 大型配体（>500 Da）：预期置信度较低
   • 多条蛋白质链：置信度可能降低
   • 新型蛋白质家族：模型表现可能不佳
3. 多个样本：检查排名前 3-5 的预测结果，关注是否一致

详细指南： 使用 Read 工具阅读 references/confidence_and_limitations.md

自定义参数

使用自定义配置

针对特定使用场景创建自定义配置：

# Copy template
cp assets/custom_inference_config.yaml my_config.yaml

# Edit parameters (see template for presets)
# Then run with custom config
python -m inference \
  --config my_config.yaml \
  --protein_ligand_csv input.csv \
  --out_dir results/

需要调整的关键参数

采样密度：

• samples_per_complex: 10 → 对困难案例增加到 20-40
• 更多样本 = 覆盖范围更广，但运行时间更长

推理步数：

• inference_steps: 20 → 增加到 25-30 以提高准确度
• 步数越多 = 质量可能越好，但速度更慢

温度参数（控制多样性）：

• temp_sampling_tor: 7.04 → 对柔性配体调高（8-10）
• temp_sampling_tor: 7.04 → 对刚性配体调低（5-6）
• 温度越高 = 构象姿势越多样

模板中提供的预设：

1. 高准确度：更多样本和步数，较低温度
2. 快速筛选：更少样本，速度更快
3. 柔性配体：提高扭转温度
4. 刚性配体：降低扭转温度

完整参数参考： 使用 Read 工具阅读 references/parameters_reference.md

高级技巧

集合对接（蛋白质柔性）

对于已知具有柔性的蛋白质，对接多种构象：

# Create ensemble CSV
import pandas as pd

conformations = ["conf1.pdb", "conf2.pdb", "conf3.pdb"]
ligand = "CC(=O)Oc1ccccc1C(=O)O"

data = {
    "complex_name": [f"ensemble_{i}" for i in range(len(conformations))],
    "protein_path": conformations,
    "ligand_description": [ligand] * len(conformations),
    "protein_sequence": [""] * len(conformations)
}

pd.DataFrame(data).to_csv("ensemble_input.csv", index=False)

使用更高的采样量运行对接（在 YAML 副本中设置 samples_per_complex: 20 — --samples_per_complex 标志会被默认配置覆盖）：

cp default_inference_args.yaml ensemble_args.yaml   # edit: samples_per_complex: 20
python -m inference \
  --config ensemble_args.yaml \
  --protein_ligand_csv ensemble_input.csv \
  --out_dir results/ensemble/

与评分函数集成

DiffDock 生成构象；结合其他工具评估亲和力：

GNINA（快速神经网络评分）：

for pose in results/*.sdf; do
    gnina -r protein.pdb -l "$pose" --score_only
done

MM/GBSA（更准确，但更慢）： 能量最小化后，使用 AmberTools MMPBSA.py 或 gmx_MMPBSA

自由能计算（最准确）： 使用 OpenMM + OpenFE 或 GROMACS 进行 FEP/TI 计算

推荐工作流：

1. DiffDock → 生成带置信度评分的构象
2. 目视检查 → 检查结构合理性
3. GNINA 或 MM/GBSA → 重新评分并按亲和力排序
4. 实验验证 → 生化测定

局限性与适用范围

DiffDock 适用于：

• 小分子配体（通常为 100-1000 Da）
• 类药有机化合物
• 小肽（<20 个残基）
• 单链或多链蛋白质

DiffDock 不适用于：

• 大型生物分子（蛋白质-蛋白质对接）→ 使用 DiffDock-PP 或 AlphaFold-Multimer
• 大肽（>20 个残基）→ 使用其他方法
• 共价对接 → 使用专用的共价对接工具
• 结合亲和力预测 → 结合评分函数使用
• 膜蛋白 → 并非专门针对这类蛋白训练，使用时请谨慎

完整的局限性说明： 使用 Read 工具阅读 references/confidence_and_limitations.md

故障排除

常见问题

问题：所有预测的置信度评分都很低

• 原因：配体较大或不常见、结合位点不明确、蛋白质存在柔性
• 解决方案：增加 samples_per_complex（20-40），尝试集合对接，验证蛋白质结构

问题：内存不足错误

• 原因：GPU 内存不足以支持批次大小
• 解决方案：将 --batch_size 2 调小，或一次处理更少的复合物

问题：性能缓慢

• 原因：使用 CPU 而非 GPU 运行
• 解决方案：使用 python -c "import torch; print(torch.cuda.is_available())" 验证 CUDA，并使用 GPU

问题：结合构象不合理

• 原因：蛋白质准备不充分、配体过大、结合位点错误
• 解决方案：检查蛋白质是否有缺失残基，移除距离较远的水分子，并考虑指定结合位点

问题：“Module not found”错误

• 原因：缺少依赖项或环境错误
• 解决方案：运行 python scripts/setup_check.py 进行诊断

性能优化

为获得最佳效果：

1. 使用 GPU（实际使用的必要条件）
2. 对重复使用的蛋白质预先计算 ESM 嵌入
3. 将多个复合物批量处理
4. 从默认参数开始，必要时再进行调整
5. 验证蛋白质结构（补全缺失残基）
6. 配体使用规范 SMILES

图形用户界面

如需交互式使用，请启动 Web 界面：

python app/main.py
# Navigate to http://localhost:7860

也可以尝试在线演示（https://huggingface.co/spaces/reginabarzilaygroup/DiffDock-Web）， 不过该 Space 经常无法访问——为确保可靠运行，建议使用本地或 Docker 安装。

资源

辅助脚本（scripts/）

prepare_batch_csv.py：创建并验证批次输入 CSV 文件

• 使用示例条目创建模板
• 验证文件路径和 SMILES 字符串
• 检查必需列和格式问题

analyze_results.py：分析置信度评分并为预测排序

• 解析单次或批次运行的结果
• 生成统计摘要
• 导出为 CSV，以供后续分析
• 找出不同复合物中的顶级预测

setup_check.py：验证 DiffDock 环境设置

• 检查 Python 版本和依赖项
• 验证 PyTorch 和 CUDA 是否可用
• 测试 RDKit 和 PyTorch Geometric 是否安装
• 如有需要，提供安装说明

参考文档（references/）

parameters_reference.md：完整的参数文档

• 所有命令行选项和配置参数
• 默认值和可接受的范围
• 用于控制多样性的温度参数
• 模型检查点位置和版本标志

在用户需要以下内容时阅读此文件：

• 详细的参数说明
• 针对特定系统的微调指南
• 替代采样策略

confidence_and_limitations.md：置信度分数解读和工具局限性

• 详细的置信度分数解读
• 何时可以信任预测结果
• DiffDock 的适用范围和局限性
• 与互补工具的集成
• 预测质量问题排查

在用户需要以下内容时阅读此文件：

• 置信度分数解读帮助
• 了解何时不应使用 DiffDock
• 与其他工具结合使用的指南
• 验证策略

workflows_examples.md：全面的工作流示例

• 详细的安装说明
• 所有工作流的分步示例
• 高级集成模式
• 常见问题排查
• 最佳实践和优化技巧

在用户需要以下内容时阅读此文件：

• 包含代码的完整工作流示例
• 与 GNINA、OpenMM 或其他工具集成
• 虚拟筛选工作流
• 集合对接流程

资源（assets/）

batch_template.csv：批处理模板

• 带有必需列的预格式化 CSV
• 展示不同输入类型的示例条目
• 可直接自定义并填入实际数据

custom_inference_config.yaml：配置模板

• 标注了所有参数的 YAML
• 针对常见用例的四种预设配置
• 说明各参数的详细注释
• 可直接自定义并使用

最佳实践

1. 开始大型任务前，始终使用 setup_check.py 验证环境
2. 使用 prepare_batch_csv.py 验证批处理 CSV，及早发现错误
3. 先使用默认值，再根据系统特定需求调整参数
4. 生成多个样本（10-40 个），以获得稳健的预测结果
5. 在下游分析前，目视检查排名靠前的构象
6. 结合评分函数评估亲和力
7. 使用置信度分数进行初步排序，而非最终决策
8. 为虚拟筛选任务预先计算嵌入
9. 记录所用参数，以确保结果可复现
10. 尽可能通过实验验证结果

引用

使用 DiffDock 时，请引用相应论文：

DiffDock-L（当前默认模型）：

Corso et al. (2024) "Deep Confident Steps to New Pockets: Strategies for Docking Generalization"
ICLR 2024, arXiv:2402.18396

原始 DiffDock：

Corso et al. (2023) "DiffDock: Diffusion Steps, Twists, and Turns for Molecular Docking"
ICLR 2023, arXiv:2210.01776

更多资源

• GitHub 仓库：https://github.com/gcorso/DiffDock
• 在线演示：https://huggingface.co/spaces/reginabarzilaygroup/DiffDock-Web
• DiffDock-L 论文：https://arxiv.org/abs/2402.18396
• 原始论文：https://arxiv.org/abs/2210.01776

属于 AlterLab Academic Skills 套件。