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 分）
• モデルのチェックポイント（約 500MB）が存在しない場合、自動的にダウンロードされます

主なワークフロー

ワークフロー 1：単一のタンパク質・リガンドのドッキング

用途： 1 つのリガンドを 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 は複合体ごとに 1 つのサブディレクトリを書き出します（単一実行の場合も同様）。信頼度は各ポーズのファイル名に含まれます。

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 化合物超）の場合：

すべてのタンパク質とリガンドのペアを 1 つの CSV にまとめ、inference を 1 回実行します。起動時に 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 フラグの後に適用され、 CLI フラグの値を上書きします。samples_per_complex、inference_steps、および temp_* パラメーターは default_inference_args.yaml に含まれているため、たとえば --config default_inference_args.yaml とともに --samples_per_complex 20 を指定しても効果はありません。代わりに 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 を使用します。

自由エネルギー計算（最も高精度）： FEP/TI 計算には OpenMM + OpenFE または GROMACS を使用します。

推奨ワークフロー：

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 に減らすか、一度に処理する複合体の数を減らす

問題：処理が遅い

• 原因：GPU ではなく CPU で実行している
• 解決策：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 を使用する

グラフィカルユーザーインターフェース

対話形式で使用するには、ウェブインターフェースを起動します。

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
• よくある用途向けの 4 つのプリセット設定
• 各パラメーターを説明する詳細なコメント
• カスタマイズしてすぐに使用可能

ベストプラクティス

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 スイートの一部です。