diffdock

DiffDock：拡散モデルによる分子ドッキング

概要

DiffDock は、タンパク質標的に対する低分子リガンドの 3D 結合ポーズを予測する、拡散ベースのディープラーニングツールです。計算ドッキングの最先端技術を体現しており、構造ベースの創薬やケミカルバイオロジーに不可欠です。

主な機能：

• ディープラーニングを使用して、高精度でリガンドの結合ポーズを予測
• タンパク質構造（PDB ファイル）または配列（ESMFold 経由）に対応
• 単一の複合体またはバッチ仮想スクリーニングキャンペーンを処理
• 予測の信頼性を評価する信頼度スコアを生成
• 多様なリガンド入力（SMILES、SDF、MOL2）に対応

重要な違い： DiffDock は結合ポーズ（3D 構造）と信頼度（予測の確実性）を予測しますが、結合親和性（ΔG、Kd）は予測しません。親和性の評価には、必ずスコアリング関数（GNINA、MM/GBSA）と組み合わせてください。

このスキルを使用する場面

以下の場合に、このスキルを使用してください。

• 「このリガンドをタンパク質にドッキングする」または「結合ポーズを予測する」
• 「分子ドッキングを実行する」または「タンパク質-リガンドドッキングを行う」
• 「仮想スクリーニング」または「化合物ライブラリをスクリーニングする」
• 「この分子はどこに結合するか」または「結合部位を予測する」
• 構造ベースの創薬やリード最適化のタスク
• PDB ファイルと SMILES 文字列、またはリガンド構造を扱うタスク
• 複数のタンパク質-リガンドペアのバッチドッキング

インストールと環境設定

環境の状態を確認する

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）が見つからない場合、自動的にダウンロードされます
• 現在の上流リリースは DiffDock v1.1.3 です。default_inference_args.yaml では DiffDock-L がデフォルトのモデル系列です

主なワークフロー

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

ユースケース： 1 つのリガンドを 1 つのタンパク質標的にドッキングする

入力要件：

• タンパク質：PDB ファイルまたはアミノ酸配列
• リガンド：SMILES 文字列または構造ファイル（SDF/MOL2）

コマンド：

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

代替方法（タンパク質配列を使用）：

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

出力構造：

results/single_docking/
└── complex_0/
    ├── rank1.sdf                    # Convenience copy of top-ranked pose
    ├── rank1_confidence0.87.sdf     # Top-ranked pose with confidence in filename
    ├── rank2_confidence0.42.sdf     # Second-ranked pose
    ├── ...
    └── rank10_confidence-1.23.sdf   # 10th pose (default: 10 samples)

現在の inference.py では、単一複合体の実行向けに --ligand_description が登録されています。上流の README の一部には依然として --ligand と記載されていますが、ローカルのチェックアウトで --ligand のエイリアスが明示的にサポートされていない限り、--ligand_description を使用してください。

ワークフロー 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 個超）の場合：

処理を高速化するため、タンパク質の埋め込みを事前計算します。

# Pre-compute embeddings
python datasets/esm_embedding_preparation.py \
  --protein_ligand_csv screening_input.csv \
  --out_file protein_embeddings.pt

# Run with pre-computed embeddings
python -m inference \
  --config default_inference_args.yaml \
  --protein_ligand_csv screening_input.csv \
  --esm_embeddings_path protein_embeddings.pt \
  --out_dir results/screening/

ワークフロー 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)

サンプリングを増やしてドッキングを実行します:

python -m inference \
  --config default_inference_args.yaml \
  --protein_ligand_csv ensemble_input.csv \
  --samples_per_complex 20 \
  --out_dir results/ensemble/

スコアリング関数との統合

DiffDock はポーズを生成します。親和性の評価には他のツールと組み合わせてください:

GNINA（高速なニューラルネットワークスコアリング）:

for pose in results/single_docking/complex_0/*confidence*.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 を使用する

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

対話的に利用する場合は、Web インターフェースを起動してください:

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

または、インストールせずにオンラインデモを利用することもできます:

• https://huggingface.co/spaces/reginabarzilaygroup/DiffDock-Web

リソース

ヘルパースクリプト（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

関連スキル

• rowan：Rowan は、Python API を備えたクラウドネイティブの分子モデリングおよびメディシナルケミストリーのワークフロープラットフォームです。
• tamarind：Tamarind Bio プラットフォーム上のオープンソースの分子設計および構造生物学ツールのコレクションに、REST API または MCP サーバーを介してアクセスできます…
• molfeat：計算器、scikit-learn…を提供する molfeat（0.11.0）を使用して、SMILES 文字列または RDKit/datamol 分子を数値特徴量に変換します。