diffdock

DiffDock : Amarrage Moléculaire avec Modèles de Diffusion

Aperçu

DiffDock est un outil d'apprentissage profond basé sur la diffusion pour l'amarrage moléculaire qui prédit les poses de liaison 3D de petites molécules ligands sur des cibles protéiques. Il représente l'état de l'art en amarrage computationnel, crucial pour la découverte de médicaments basée sur la structure et la biologie chimique.

Capacités principales :

• Prédire les poses de liaison des ligands avec une haute précision grâce à l'apprentissage profond
• Prendre en charge les structures protéiques (fichiers PDB) ou les séquences (via ESMFold)
• Traiter des complexes uniques ou des campagnes de criblage virtuel par lot
• Générer des scores de confiance pour évaluer la fiabilité des prédictions
• Gérer diverses entrées de ligands (SMILES, SDF, MOL2)

Distinction clé : DiffDock prédit les poses de liaison (structure 3D) et la confiance (certitude de la prédiction), PAS l'affinité de liaison (ΔG, Kd). Combinez toujours avec des fonctions de score (GNINA, MM/GBSA) pour l'évaluation de l'affinité.

Quand Utiliser Cette Compétence

Cette compétence doit être utilisée lorsque :

• "Amarre ce ligand à une protéine" ou "prédire la pose de liaison"
• "Effectuer un amarrage moléculaire" ou "réaliser un amarrage protéine-ligand"
• "Criblage virtuel" ou "cribler une bibliothèque de composés"
• "Où cette molécule se lie-t-elle ?" ou "prédire le site de liaison"
• Conception de médicaments basée sur la structure ou tâches d'optimisation de leads
• Tâches impliquant des fichiers PDB + des chaînes SMILES ou des structures de ligands
• Amarrage par lots de plusieurs paires protéine-ligand

Installation et Configuration de l'Environnement

Vérifier l'État de l'Environnement

Avant de procéder aux tâches DiffDock, vérifiez la configuration de l'environnement :

# Utiliser le vérificateur de configuration fourni
python scripts/setup_check.py

Ce script valide la version de Python, PyTorch avec CUDA, PyTorch Geometric, RDKit, ESM et autres dépendances.

Options d'Installation

Option 1 : Conda (Recommandé)

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

Notes importantes :

• GPU fortement recommandé (accélération de 10 à 100 fois vs CPU)
• La première exécution pré-calcule les tables de recherche SO(2)/SO(3) (~2-5 minutes)
• Les points de contrôle du modèle (~500 Mo) se téléchargent automatiquement s'ils ne sont pas présents
• La version amont actuelle est DiffDock v1.1.3 ; DiffDock-L est la ligne de modèle par défaut dans default_inference_args.yaml

Workflows Principaux

Workflow 1 : Amarrage Simple Protéine-Ligand

Cas d'utilisation : Amarrage d'un ligand sur une cible protéique

Exigences d'entrée :

• Protéine : fichier PDB OU séquence d'acides aminés
• Ligand : chaîne SMILES OU fichier de structure (SDF/MOL2)

Commande :

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 (séquence protéique) :

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

Structure de sortie :

results/single_docking/
└── complex_0/
    ├── rank1.sdf                    # Copie pratique de la pose la mieux classée
    ├── rank1_confidence0.87.sdf     # Pose la mieux classée avec confiance dans le nom de fichier
    ├── rank2_confidence0.42.sdf     # Deuxième pose classée
    ├── ...
    └── rank10_confidence-1.23.sdf   # 10e pose (par défaut : 10 échantillons)

Le inference.py actuel enregistre --ligand_description pour les exécutions sur un seul complexe. Certains textes README en amont disent encore --ligand ; utilisez --ligand_description sauf si votre copie locale prend explicitement en charge un alias --ligand.

Workflow 2 : Traitement par Lots de Plusieurs Complexes

Cas d'utilisation : Amarrage de plusieurs ligands sur des protéines, campagnes de criblage virtuel

Étape 1 : Préparer le CSV par Lots

Utilisez le script fourni pour créer ou valider l'entrée par lots :

# Créer un modèle
python scripts/prepare_batch_csv.py --create --output batch_input.csv

# Valider un CSV existant
python scripts/prepare_batch_csv.py my_input.csv --validate

Format 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,

Colonnes Requises :

• complex_name : Identifiant unique
• protein_path : Chemin du fichier PDB (laisser vide si on utilise la séquence)
• ligand_description : Chaîne SMILES ou chemin du fichier ligand
• protein_sequence : Séquence d'acides aminés (laisser vide si on utilise le PDB)

Étape 2 : Exécuter l'Amarrage par Lots

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

Pour les Gros Criblages Virtuels (>100 composés) :

Pré-calculez les embeddings protéiques pour un traitement plus rapide :

# Pré-calculer les embeddings
python datasets/esm_embedding_preparation.py \
  --protein_ligand_csv screening_input.csv \
  --out_file protein_embeddings.pt

# Exécuter avec embeddings pré-calculés
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 : Analyse des Résultats

Après la fin de l'amarrage, analysez les scores de confiance et classez les prédictions :

# Analyser tous les résultats
python scripts/analyze_results.py results/batch/

# Afficher les 5 meilleurs par complexe
python scripts/analyze_results.py results/batch/ --top 5

# Filtrer par seuil de confiance
python scripts/analyze_results.py results/batch/ --threshold 0.0

# Exporter vers CSV
python scripts/analyze_results.py results/batch/ --export summary.csv

# Afficher les 20 meilleures prédictions tous complexes confondus
python scripts/analyze_results.py results/batch/ --best 20

Le script d'analyse :

• Analyse les scores de confiance de toutes les prédictions
• Classe comme Élevée (>0), Modérée (-1.5 à 0) ou Faible (<-1.5)
• Classe les prédictions au sein des complexes et entre eux
• Génère des résumés statistiques
• Exporte les résultats vers CSV pour analyse en aval

Interprétation du Score de Confiance

Comprendre les Scores :

Plage de Scores	Niveau de Confiance	Interprétation
> 0	Élevée	Prédiction forte, probablement précise
-1.5 à 0	Modérée	Prédiction raisonnable, valider soigneusement
< -1.5	Faible	Prédiction incertaine, nécessite validation

Notes Critiques :

1. Confiance ≠ Affinité : Une confiance élevée signifie la certitude du modèle sur la structure, PAS une liaison forte
2. Le Contexte Compte : Ajustez les attentes pour :
   • Gros ligands (>500 Da) : Confiance plus faible attendue
   • Plusieurs chaînes protéiques : Peut diminuer la confiance
   • Nouvelles familles de protéines : Peut sous-performer
3. Échantillons Multiples : Examinez les 3 à 5 meilleures prédictions, recherchez un consensus

Pour des conseils détaillés : Lisez references/confidence_and_limitations.md avec l'outil de lecture

Personnalisation des Paramètres

Utilisation d'une Configuration Personnalisée

Créez une configuration personnalisée pour des cas d'utilisation spécifiques :

# Copier le modèle
cp assets/custom_inference_config.yaml my_config.yaml

# Modifier les paramètres (voir le modèle pour les préréglages)
# Puis exécuter avec la configuration personnalisée
python -m inference \
  --config my_config.yaml \
  --protein_ligand_csv input.csv \
  --out_dir results/

Paramètres Clés à Ajuster

Densité d'Échantillonnage :

• samples_per_complex: 10 → Augmenter à 20-40 pour les cas difficiles
• Plus d'échantillons = meilleure couverture mais temps d'exécution plus long

Étapes d'Inférence :

• inference_steps: 20 → Augmenter à 25-30 pour une meilleure précision
• Plus d'étapes = qualité potentiellement meilleure mais plus lente

Paramètres de Température (contrôle de la diversité) :

• temp_sampling_tor: 7.04 → Augmenter pour les ligands flexibles (8-10)
• temp_sampling_tor: 7.04 → Diminuer pour les ligands rigides (5-6)
• Température plus élevée = poses plus diverses

Préréglages Disponibles dans le Modèle :

1. Haute Précision : Plus d'échantillons + étapes, température plus basse
2. Criblage Rapide : Moins d'échantillons, plus rapide
3. Ligands Flexibles : Température de torsion augmentée
4. Ligands Rigides : Température de torsion diminuée

Pour une référence complète des paramètres : Lisez references/parameters_reference.md avec l'outil de lecture

Techniques Avancées

Amarrage d'Ensemble (Flexibilité Protéique)

Pour les protéines avec une flexibilité connue, amarrez sur plusieurs conformations :

# Créer un CSV d'ensemble
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)

Exécutez l'amarrage avec un échantillonnage accru :

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

Intégration avec des Fonctions de Score

DiffDock génère des poses ; combinez avec d'autres outils pour l'affinité :

GNINA (Score réseau neuronal rapide) :

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

MM/GBSA (Plus précis, plus lent) : Utilisez AmberTools MMPBSA.py ou gmx_MMPBSA après minimisation d'énergie

Calculs d'Énergie Libre (Les plus précis) : Utilisez OpenMM + OpenFE ou GROMACS pour les calculs FEP/TI

Workflow Recommandé :

1. DiffDock → Générer des poses avec scores de confiance
2. Inspection visuelle → Vérifier la plausibilité structurale
3. GNINA ou MM/GBSA → Re-scorer et classer par affinité
4. Validation expérimentale → Tests biochimiques

Limitations et Portée

DiffDock EST CONÇU POUR :

• Petites molécules ligands (typiquement 100-1000 Da)
• Composés organiques de type médicamenteux
• Petits peptides (<20 résidus)
• Protéines simple ou multi-chaînes

DiffDock N'EST PAS CONÇU POUR :

• Grosses biomolécules (amarrage protéine-protéine) → Utilisez DiffDock-PP ou AlphaFold-Multimer
• Gros peptides (>20 résidus) → Utilisez des méthodes alternatives
• Amarrage covalent → Utilisez des outils d'amarrage covalent spécialisés
• Prédiction d'affinité de liaison → Combinez avec des fonctions de score
• Protéines membranaires → Non spécifiquement entraîné, utilisez avec prudence

Pour les limitations complètes : Lisez references/confidence_and_limitations.md avec l'outil de lecture

Dépannage

Problèmes Courants

Problème : Scores de confiance faibles dans toutes les prédictions

• Cause : Ligands gros/inhabituels, site de liaison peu clair, flexibilité protéique
• Solution : Augmentez samples_per_complex (20-40), essayez l'amarrage d'ensemble, validez la structure protéique

Problème : Erreurs de mémoire insuffisante

• Cause : Mémoire GPU insuffisante pour la taille du lot
• Solution : Réduisez --batch_size 2 ou traitez moins de complexes à la fois

Problème : Performances lentes

• Cause : Exécution sur CPU au lieu de GPU
• Solution : Vérifiez CUDA avec python -c "import torch; print(torch.cuda.is_available())", utilisez GPU

Problème : Poses de liaison irréalistes

• Cause : Mauvaise préparation de la protéine, ligand trop gros, mauvais site de liaison
• Solution : Vérifiez la protéine pour les résidus manquants, retirez les molécules d'eau éloignées, envisagez de spécifier le site de liaison

Problème : Erreurs "Module non trouvé"

• Cause : Dépendances manquantes ou mauvais environnement
• Solution : Exécutez python scripts/setup_check.py pour diagnostiquer

Optimisation des Performances

Pour les Meilleurs Résultats :

1. Utilisez GPU (essentiel pour une utilisation pratique)
2. Pré-calculez les embeddings ESM pour une utilisation répétée de la protéine
3. Traitez plusieurs complexes par lots ensemble
4. Commencez avec les paramètres par défaut, puis ajustez si nécessaire
5. Validez les structures protéiques (résolvez les résidus manquants)
6. Utilisez des SMILES canoniques pour les ligands

Interface Graphique Utilisateur

Pour une utilisation interactive, lancez l'interface web :

python app/main.py
# Naviguez vers http://localhost:7860

Ou utilisez la démo en ligne sans installation :

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

Ressources

Scripts d'Aide (scripts/)

prepare_batch_csv.py : Créer et valider des fichiers CSV d'entrée par lots

• Créer des modèles avec des exemples d'entrées
• Valider les chemins de fichiers et les chaînes SMILES
• Vérifier les colonnes requises et les problèmes de format

analyze_results.py : Analyser les scores de confiance et classer les prédictions

• Analyser les résultats d'exécutions simples ou par lots
• Générer des résumés statistiques
• Exporter vers CSV pour analyse en aval
• Identifier les meilleures prédictions tous complexes confondus

setup_check.py : Vérifier la configuration de l'environnement DiffDock

• Vérifier la version de Python et les dépendances
• Vérifier la disponibilité de PyTorch et CUDA
• Tester l'installation de RDKit et PyTorch Geometric
• Fournir des instructions d'installation si nécessaire

Documentation de Référence (references/)

parameters_reference.md : Documentation complète des paramètres

• Toutes les options de ligne de commande et paramètres de configuration
• Valeurs par défaut et plages acceptables
• Paramètres de température pour contrôler la diversité
• Emplacements des points de contrôle du modèle et indicateurs de version

Lisez ce fichier lorsque les utilisateurs ont besoin de :

• Explications détaillées des paramètres
• Conseils d'ajustement fin pour des systèmes spécifiques
• Stratégies d'échantillonnage alternatives

confidence_and_limitations.md : Interprétation du score de confiance et limitations de l'outil

• Interprétation détaillée du score de confiance
• Quand faire confiance aux prédictions
• Portée et limitations de DiffDock
• Intégration avec des outils complémentaires
• Dépannage de la qualité des prédictions

Lisez ce fichier lorsque les utilisateurs ont besoin de :

• Aide pour interpréter les scores de confiance
• Comprendre quand NE PAS utiliser DiffDock
• Conseils sur la combinaison avec d'autres outils
• Stratégies de validation

workflows_examples.md : Exemples complets de workflows

• Instructions d'installation détaillées
• Exemples pas à pas pour tous les workflows
• Modèles d'intégration avancés
• Dépannage des problèmes courants
• Meilleures pratiques et conseils d'optimisation

Lisez ce fichier lorsque les utilisateurs ont besoin de :

• Exemples complets de workflows avec code
• Intégration avec GNINA, OpenMM ou d'autres outils
• Workflows de criblage virtuel
• Procédures d'amarrage d'ensemble

Actifs (assets/)

batch_template.csv : Modèle de fichier CSV d'entrée par lots avec exemples d'entrées custom_inference_config.yaml : Modèle de fichier de configuration d'inférence personnalisée avec préréglages