diffdock

DiffDock: Molekulares Docking mit Diffusionsmodellen

Überblick

DiffDock ist ein auf Diffusion basierendes Deep-Learning-Tool für molekulares Docking, das 3D-Bindungsmodi kleiner Molekül-Liganden an Protein-Targets vorhersagt. Es repräsentiert den aktuellen Stand der Technik im rechnergestützten Docking und ist entscheidend für die strukturbasierte Wirkstoffentwicklung und chemische Biologie.

Kernfunktionen:

• Vorhersage von Liganden-Bindungsmodi mit hoher Genauigkeit durch Deep Learning
• Unterstützung von Proteinstrukturen (PDB-Dateien) oder Sequenzen (über ESMFold)
• Verarbeitung einzelner Komplexe oder Batch-Virtual-Screening-Kampagnen
• Generierung von Konfidenzwerten zur Bewertung der Vorhersagezuverlässigkeit
• Handhabung verschiedener Ligandeneingaben (SMILES, SDF, MOL2)

Wichtige Unterscheidung: DiffDock sagt Bindungsmodi (3D-Struktur) und Konfidenz (Vorhersagesicherheit) vorher, NICHT die Bindungsaffinität (ΔG, Kd). Kombinieren Sie es immer mit Scoring-Funktionen (GNINA, MM/GBSA) für die Affinitätsbewertung.

Wann diese Fähigkeit verwendet werden sollte

Diese Fähigkeit sollte verwendet werden, wenn:

• „Docke diesen Liganden an ein Protein“ oder „sage den Bindungsmodus vorher“
• „Führe molekulares Docking durch“ oder „führe Protein-Ligand-Docking durch“
• „Virtuelles Screening“ oder „durchsuche eine Verbindungsbibliothek“
• „Wo bindet dieses Molekül?“ oder „sage die Bindungsstelle vorher“
• Strukturbasierte Wirkstoffentwicklung oder Leitstrukturoptimierungsaufgaben
• Aufgaben mit PDB-Dateien + SMILES-Strings oder Ligandenstrukturen
• Batch-Docking mehrerer Protein-Ligand-Paare

Installation und Umgebungseinrichtung

Überprüfung des Umgebungsstatus

Überprüfen Sie vor der Durchführung von DiffDock-Aufgaben die Umgebungseinrichtung:

# Verwenden Sie den bereitgestellten Setup-Checker
python scripts/setup_check.py

Dieses Skript validiert die Python-Version, PyTorch mit CUDA, PyTorch Geometric, RDKit, ESM und andere Abhängigkeiten.

Installationsoptionen

Option 1: Conda (Empfohlen)

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

Option 2: Docker

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

Wichtige Hinweise:

• GPU wird dringend empfohlen (10-100x Geschwindigkeitssteigerung gegenüber CPU)
• Der erste Lauf berechnet SO(2)/SO(3)-Lookup-Tabellen vor (ca. 2–5 Minuten)
• Modell-Checkpoints (~500 MB) werden automatisch heruntergeladen, falls nicht vorhanden
• Der aktuelle Upstream-Release ist DiffDock v1.1.3; DiffDock-L ist die Standard-Modelllinie in default_inference_args.yaml

Kern-Workflows

Workflow 1: Einzelnes Protein-Ligand-Docking

Anwendungsfall: Einen Liganden an ein einzelnes Protein-Target andocken

Eingabeanforderungen:

• Protein: PDB-Datei ODER Aminosäuresequenz
• Ligand: SMILES-String ODER Strukturdatei (SDF/MOL2)

Befehl:

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

Alternative (Proteinsequenz):

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

Ausgabestruktur:

results/single_docking/
└── complex_0/
    ├── rank1.sdf                    # Kopie des am besten bewerteten Modus
    ├── rank1_confidence0.87.sdf     # Am besten bewerteter Modus mit Konfidenz im Dateinamen
    ├── rank2_confidence0.42.sdf     # Zweitbester Modus
    ├── ...
    └── rank10_confidence-1.23.sdf   # 10. Modus (Standard: 10 Samples)

Das aktuelle inference.py registriert --ligand_description für Einzelkomplex-Läufe. Einige README-Texte des Upstream-Projekts sagen noch --ligand; verwenden Sie --ligand_description, es sei denn, Ihr lokaler Checkout unterstützt explizit einen --ligand-Alias.

Workflow 2: Batch-Verarbeitung mehrerer Komplexe

Anwendungsfall: Mehrere Liganden an Proteine andocken, Virtual-Screening-Kampagnen

Schritt 1: Batch-CSV vorbereiten

Verwenden Sie das bereitgestellte Skript, um eine Batch-Eingabe zu erstellen oder zu validieren:

# Vorlage erstellen
python scripts/prepare_batch_csv.py --create --output batch_input.csv

# Vorhandene CSV validieren
python scripts/prepare_batch_csv.py my_input.csv --validate

CSV-Format:

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,

Erforderliche Spalten:

• complex_name: Eindeutiger Bezeichner
• protein_path: Pfad zur PDB-Datei (leer lassen, wenn Sequenz verwendet wird)
• ligand_description: SMILES-String oder Liganden-Dateipfad
• protein_sequence: Aminosäuresequenz (leer lassen, wenn PDB verwendet wird)

Schritt 2: Batch-Docking ausführen

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

Für große virtuelle Screenings (>100 Verbindungen):

Berechnen Sie Protein-Embeddings für eine schnellere Verarbeitung vor:

# Embeddings vorberechnen
python datasets/esm_embedding_preparation.py \
  --protein_ligand_csv screening_input.csv \
  --out_file protein_embeddings.pt

# Mit vorberechneten Embeddings ausführen
python -m inference \
  --config default_inference_args.yaml \
  --protein_ligand_csv screening_input.csv \
  --esm_embeddings_path protein_embeddings.pt \
  --out_dir results/screening/

Workflow 3: Ergebnisse analysieren

Nach Abschluss des Dockings können Sie Konfidenzwerte analysieren und Vorhersagen bewerten:

# Alle Ergebnisse analysieren
python scripts/analyze_results.py results/batch/

# Top 5 pro Komplex anzeigen
python scripts/analyze_results.py results/batch/ --top 5

# Nach Konfidenzschwellenwert filtern
python scripts/analyze_results.py results/batch/ --threshold 0.0

# Als CSV exportieren
python scripts/analyze_results.py results/batch/ --export summary.csv

# Top 20 Vorhersagen über alle Komplexe anzeigen
python scripts/analyze_results.py results/batch/ --best 20

Das Analyseskript:

• Extrahiert Konfidenzwerte aus allen Vorhersagen
• Klassifiziert als Hoch (>0), Mittel (-1.5 bis 0) oder Niedrig (<-1.5)
• Bewertet Vorhersagen innerhalb und zwischen Komplexen
• Erstellt statistische Zusammenfassungen
• Exportiert Ergebnisse als CSV für die nachgelagerte Analyse

Interpretation der Konfidenzwerte

Werte verstehen:

Wertebereich	Konfidenzniveau	Interpretation
> 0	Hoch	Starke Vorhersage, wahrscheinlich genau
-1.5 bis 0	Mittel	Angemessene Vorhersage, sorgfältig validieren
< -1.5	Niedrig	Unsichere Vorhersage, erfordert Validierung

Wichtige Hinweise:

1. Konfidenz ≠ Affinität: Hohe Konfidenz bedeutet Sicherheit des Modells bezüglich der Struktur, NICHT starke Bindung
2. Kontextabhängigkeit: Passen Sie die Erwartungen an:
   • Große Liganden (>500 Da): Niedrigere Konfidenz zu erwarten
   • Mehrere Proteinketten: Kann die Konfidenz verringern
   • Neue Proteinfamilien: Kann schlechter abschneiden
3. Mehrere Samples: Überprüfen Sie die Top 3-5 Vorhersagen und suchen Sie nach Konsens

Detaillierte Anleitung: Lesen Sie references/confidence_and_limitations.md mit dem Read-Tool

Parameteranpassung

Benutzerdefinierte Konfiguration verwenden

Erstellen Sie eine benutzerdefinierte Konfiguration für spezifische Anwendungsfälle:

# Vorlage kopieren
cp assets/custom_inference_config.yaml my_config.yaml

# Parameter bearbeiten (siehe Vorlage für Voreinstellungen)
# Dann mit benutzerdefinierter Konfiguration ausführen
python -m inference \
  --config my_config.yaml \
  --protein_ligand_csv input.csv \
  --out_dir results/

Wichtige anzupassende Parameter

Sampling-Dichte:

• samples_per_complex: 10 → Erhöhen auf 20-40 für schwierige Fälle
• Mehr Samples = bessere Abdeckung, aber längere Laufzeit

Inferenzschritte:

• inference_steps: 20 → Erhöhen auf 25-30 für höhere Genauigkeit
• Mehr Schritte = potenziell bessere Qualität, aber langsamer

Temperaturparameter (kontrollieren die Diversität):

• temp_sampling_tor: 7.04 → Erhöhen für flexible Liganden (8-10)
• temp_sampling_tor: 7.04 → Verringern für starre Liganden (5-6)
• Höhere Temperatur = vielfältigere Modi

Verfügbare Voreinstellungen in der Vorlage:

1. Hohe Genauigkeit: Mehr Samples + Schritte, niedrigere Temperatur
2. Schnelles Screening: Weniger Samples, schneller
3. Flexible Liganden: Erhöhte Torsionstemperatur
4. Starre Liganden: Verringerte Torsionstemperatur

Vollständige Parameterreferenz: Lesen Sie references/parameters_reference.md mit dem Read-Tool

Fortgeschrittene Techniken

Ensemble-Docking (Proteinflexibilität)

Bekannte flexible Proteine können mit mehreren Konformationen gedockt werden:

# Ensemble-CSV erstellen
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)

Docking mit erhöhtem Sampling ausführen:

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

Integration mit Scoring-Funktionen

DiffDock generiert Modi; kombinieren Sie es mit anderen Tools für die Affinitätsbewertung:

GNINA (Schnelles neuronales Netzwerk-Scoring):

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

MM/GBSA (Genauer, langsamer): Verwenden Sie AmberTools MMPBSA.py oder gmx_MMPBSA nach der Energieminimierung

Freie-Energie-Berechnungen (am genauesten): Verwenden Sie OpenMM + OpenFE oder GROMACS für FEP/TI-Berechnungen

Empfohlener Workflow:

1. DiffDock → Modi mit Konfidenzwerten generieren
2. Visuelle Inspektion → Strukturelle Plausibilität prüfen
3. GNINA oder MM/GBSA → Neu bewerten und nach Affinität sortieren
4. Experimentelle Validierung → Biochemische Assays

Einschränkungen und Anwendungsbereich

DiffDock IST GEEIGNET für:

• Kleine Molekül-Liganden (typischerweise 100-1000 Da)
• Wirkstoffähnliche organische Verbindungen
• Kleine Peptide (<20 Reste)
• Einzel- oder mehrkettige Proteine

DiffDock IST NICHT GEEIGNET für:

• Große Biomoleküle (Protein-Protein-Docking) → Verwenden Sie DiffDock-PP oder AlphaFold-Multimer
• Große Peptide (>20 Reste) → Verwenden Sie alternative Methoden
• Kovalentes Docking → Verwenden Sie spezialisierte kovalente Docking-Tools
• Bindungsaffinitätsvorhersage → Kombinieren Sie mit Scoring-Funktionen
• Membranproteine → Nicht spezifisch trainiert, mit Vorsicht verwenden

Vollständige Einschränkungen: Lesen Sie references/confidence_and_limitations.md mit dem Read-Tool

Fehlerbehebung

Häufige Probleme

Problem: Niedrige Konfidenzwerte bei allen Vorhersagen

• Ursache: Große/ungewöhnliche Liganden, unklare Bindungsstelle, Proteinflexibilität
• Lösung: Erhöhen Sie samples_per_complex (20-40), versuchen Sie Ensemble-Docking, validieren Sie die Proteinstruktur

Problem: Speicherfehler

• Ursache: GPU-Speicher reicht nicht für die Batch-Größe
• Lösung: Reduzieren Sie --batch_size 2 oder verarbeiten Sie weniger Komplexe gleichzeitig

Problem: Langsame Leistung

• Ursache: Ausführung auf CPU statt GPU
• Lösung: Überprüfen Sie CUDA mit python -c "import torch; print(torch.cuda.is_available())", verwenden Sie GPU

Problem: Unrealistische Bindungsmodi

• Ursache: Schlechte Proteinvorbereitung, zu großer Ligand, falsche Bindungsstelle
• Lösung: Überprüfen Sie das Protein auf fehlende Reste, entfernen Sie entfernte Wasser, erwägen Sie die Angabe der Bindungsstelle

Problem: „Module not found“-Fehler

• Ursache: Fehlende Abhängigkeiten oder falsche Umgebung
• Lösung: Führen Sie python scripts/setup_check.py zur Diagnose aus

Leistungsoptimierung

Für beste Ergebnisse:

1. GPU verwenden (für den praktischen Einsatz unerlässlich)
2. ESM-Embeddings für wiederholte Proteinverwendung vorberechnen
3. Mehrere Komplexe zusammen stapelverarbeiten
4. Mit Standardparametern beginnen, dann bei Bedarf anpassen
5. Proteinstrukturen validieren (fehlende Reste auflösen)
6. Kanonische SMILES für Liganden verwenden

Grafische Benutzeroberfläche

Für die interaktive Nutzung starten Sie die Weboberfläche:

python app/main.py
# Navigieren Sie zu http://localhost:7860

Oder verwenden Sie die Online-Demo ohne Installation:

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

Ressourcen

Hilfsskripte (scripts/)

prepare_batch_csv.py: Batch-Eingabe-CSV-Dateien erstellen und validieren

• Vorlagen mit Beispieleinträgen erstellen
• Dateipfade und SMILES-Strings validieren
• Auf erforderliche Spalten und Formatprobleme prüfen

analyze_results.py: Konfidenzwerte analysieren und Vorhersagen bewerten

• Ergebnisse aus Einzel- oder Batch-Läufen parsen
• Statistische Zusammenfassungen erstellen
• Als CSV für nachgelagerte Analysen exportieren
• Top-Vorhersagen über Komplexe hinweg identifizieren

setup_check.py: DiffDock-Umgebungseinrichtung überprüfen

• Python-Version und Abhängigkeiten prüfen
• PyTorch- und CUDA-Verfügbarkeit überprüfen
• RDKit- und PyTorch-Geometric-Installation testen
• Installationsanweisungen bereitstellen, falls erforderlich

Referenzdokumentation (references/)

parameters_reference.md: Vollständige Parameterdokumentation

• Alle Befehlszeilenoptionen und Konfigurationsparameter
• Standardwerte und zulässige Bereiche
• Temperaturparameter zur Steuerung der Diversität
• Modell-Checkpoint-Speicherorte und Versionsflags

Lesen Sie diese Datei, wenn Benutzer Folgendes benötigen:

• Detaillierte Parametereklärungen
• Feinabstimmungsanleitung für bestimmte Systeme
• Alternative Sampling-Strategien

confidence_and_limitations.md: Interpretation der Konfidenzwerte und Tool-Einschränkungen

• Detaillierte Interpretation der Konfidenzwerte
• Wann Vorhersagen vertrauenswürdig sind
• Umfang und Einschränkungen von DiffDock
• Integration mit komplementären Tools
• Fehlerbehebung bei der Vorhersagequalität

Lesen Sie diese Datei, wenn Benutzer Folgendes benötigen:

• Hilfe bei der Interpretation von Konfidenzwerten
• Verständnis, wann DiffDock NICHT verwendet werden sollte
• Anleitung zur Kombination mit anderen Tools
• Validierungsstrategien

workflows_examples.md: Umfassende Workflow-Beispiele

• Detaillierte Installationsanweisungen
• Schritt-für-Schritt-Beispiele für alle Workflows
• Fortgeschrittene Integrationsmuster
• Fehlerbehebung bei häufigen Problemen
• Best Practices und Optimierungstipps

Lesen Sie diese Datei, wenn Benutzer Folgendes benötigen:

• Vollständige Workflow-Beispiele mit Code
• Integration mit GNINA, OpenMM oder anderen Tools
• Virtual-Screening-Workflows
• Ensemble-Docking-Verfahren

Assets (assets/)

batch_template.csv: Vorlage für Batch-Eingabe

• Beispiel-Eingabeformat zum Erstellen eigener CSVs
• Enthaltene Beispiele: Standard-, Sequenz-basierte und gemischte Dateieingaben

custom_inference_config.yaml: Vorlage für benutzerdefinierte Konfiguration

• Voreinstellungen für gängige Szenarien
• Kommentierte Parameter für einfache Anpassung

Referenzen und Zitieren

Wenn Sie DiffDock in Ihrer Forschung verwenden, zitieren Sie bitte:

• Hauptarbeit: Corso, G., Stärk, H., Jing, B., Barzilay, R., & Jaakkola, T. (2022). DiffDock: Diffusion Steps, Twists, and Turns for Molecular Docking. International Conference on Learning Representations (ICLR).
• DiffDock-L: Corso, G., Deng, A., Polizzi, N., Barzilay, R., & Jaakkola, T. (2023). Deep Confident Steps to New Pockets: Strategies for Docking Generalization.

Lizenz

DiffDock wird unter der MIT-Lizenz vertrieben. Siehe die LICENSE-Datei im Repository für Details.