diffdock

DiffDock: Acoplamiento Molecular con Modelos de Difusión

Resumen

DiffDock es una herramienta de aprendizaje profundo basada en difusión para el acoplamiento molecular que predice las poses de unión 3D de ligandos de moléculas pequeñas a proteínas diana. Representa el estado del arte en acoplamiento computacional, crucial para el descubrimiento de fármacos basado en estructura y la biología química.

Capacidades principales:

• Predecir poses de unión de ligandos con alta precisión usando aprendizaje profundo
• Soporta estructuras de proteínas (archivos PDB) o secuencias (mediante ESMFold)
• Procesar complejos individuales o campañas de cribado virtual por lotes
• Generar puntuaciones de confianza para evaluar la fiabilidad de la predicción
• Manejar diversas entradas de ligandos (SMILES, SDF, MOL2)

Distinción clave: DiffDock predice poses de unión (estructura 3D) y confianza (certeza de la predicción), NO la afinidad de unión (ΔG, Kd). Combínalo siempre con funciones de puntuación (GNINA, MM/GBSA) para evaluar la afinidad.

Cuándo usar esta habilidad

Esta habilidad debe usarse cuando:

• "Acopla este ligando a una proteína" o "predice la pose de unión"
• "Ejecuta acoplamiento molecular" o "realiza acoplamiento proteína-ligando"
• "Cribado virtual" o "examina una biblioteca de compuestos"
• "¿Dónde se une esta molécula?" o "predice el sitio de unión"
• Diseño de fármacos basado en estructura o tareas de optimización de líderes
• Tareas que involucran archivos PDB + cadenas SMILES o estructuras de ligandos
• Acoplamiento por lotes de múltiples pares proteína-ligando

Instalación y configuración del entorno

Verificar el estado del entorno

Antes de proceder con tareas de DiffDock, verifica la configuración del entorno:

# Usa el verificador de configuración proporcionado
python scripts/setup_check.py

Este script valida la versión de Python, PyTorch con CUDA, PyTorch Geometric, RDKit, ESM y otras dependencias.

Opciones de instalación

Opción 1: Conda (Recomendada)

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

Opción 2: Docker

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

Notas importantes:

• GPU fuertemente recomendada (aceleración de 10-100x frente a CPU)
• La primera ejecución precalcula las tablas de búsqueda SO(2)/SO(3) (~2-5 minutos)
• Los puntos de control del modelo (~500MB) se descargan automáticamente si no están presentes
• La versión ascendente actual es DiffDock v1.1.3; DiffDock-L es la línea de modelo predeterminada en default_inference_args.yaml

Flujos de trabajo principales

Flujo de trabajo 1: Acoplamiento único proteína-ligando

Caso de uso: Acoplar un ligando a una proteína diana

Requisitos de entrada:

• Proteína: archivo PDB O secuencia de aminoácidos
• Ligando: cadena SMILES O archivo de estructura (SDF/MOL2)

Comando:

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

Alternativa (secuencia de proteína):

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

Estructura de salida:

results/single_docking/
└── complex_0/
    ├── rank1.sdf                    # Copia de conveniencia de la pose mejor clasificada
    ├── rank1_confidence0.87.sdf     # Pose mejor clasificada con confianza en el nombre
    ├── rank2_confidence0.42.sdf     # Segunda pose mejor clasificada
    ├── ...
    └── rank10_confidence-1.23.sdf   # 10ª pose (predeterminado: 10 muestras)

El inference.py actual registra --ligand_description para ejecuciones de un solo complejo. Algunos textos README upstream aún dicen --ligand; usa --ligand_description a menos que tu clon local admita explícitamente un alias --ligand.

Flujo de trabajo 2: Procesamiento por lotes de múltiples complejos

Caso de uso: Acoplar múltiples ligandos a proteínas, campañas de cribado virtual

Paso 1: Preparar CSV por lotes

Usa el script proporcionado para crear o validar la entrada por lotes:

# Crear plantilla
python scripts/prepare_batch_csv.py --create --output batch_input.csv

# Validar CSV existente
python scripts/prepare_batch_csv.py my_input.csv --validate

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

Columnas requeridas:

• complex_name: Identificador único
• protein_path: Ruta del archivo PDB (déjalo vacío si usas secuencia)
• ligand_description: Cadena SMILES o ruta del archivo del ligando
• protein_sequence: Secuencia de aminoácidos (déjala vacía si usas PDB)

Paso 2: Ejecutar acoplamiento por lotes

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

Para cribado virtual grande (>100 compuestos):

Precalcula incrustaciones de proteínas para un procesamiento más rápido:

# Precalcular incrustaciones
python datasets/esm_embedding_preparation.py \
  --protein_ligand_csv screening_input.csv \
  --out_file protein_embeddings.pt

# Ejecutar con incrustaciones precalculadas
python -m inference \
  --config default_inference_args.yaml \
  --protein_ligand_csv screening_input.csv \
  --esm_embeddings_path protein_embeddings.pt \
  --out_dir results/screening/

Flujo de trabajo 3: Análisis de resultados

Después de completar el acoplamiento, analiza las puntuaciones de confianza y clasifica las predicciones:

# Analizar todos los resultados
python scripts/analyze_results.py results/batch/

# Mostrar las 5 mejores por complejo
python scripts/analyze_results.py results/batch/ --top 5

# Filtrar por umbral de confianza
python scripts/analyze_results.py results/batch/ --threshold 0.0

# Exportar a CSV
python scripts/analyze_results.py results/batch/ --export summary.csv

# Mostrar las 20 mejores predicciones en todos los complejos
python scripts/analyze_results.py results/batch/ --best 20

El script de análisis:

• Analiza las puntuaciones de confianza de todas las predicciones
• Clasifica como Alta (>0), Moderada (-1.5 a 0) o Baja (<-1.5)
• Clasifica las predicciones dentro y entre complejos
• Genera resúmenes estadísticos
• Exporta resultados a CSV para análisis posteriores

Interpretación de la puntuación de confianza

Entendiendo las puntuaciones:

Rango de puntuación	Nivel de confianza	Interpretación
> 0	Alta	Predicción sólida, probablemente precisa
-1.5 a 0	Moderada	Predicción razonable, validar con cuidado
< -1.5	Baja	Predicción incierta, requiere validación

Notas críticas:

1. Confianza ≠ Afinidad: Alta confianza significa certeza del modelo sobre la estructura, NO unión fuerte
2. El contexto importa: Ajusta las expectativas para:
   • Ligandos grandes (>500 Da): Se espera menor confianza
   • Múltiples cadenas de proteínas: Puede disminuir la confianza
   • Familias de proteínas novedosas: Puede tener un rendimiento inferior
3. Múltiples muestras: Revisa las 3-5 mejores predicciones, busca consenso

Para obtener orientación detallada: Lee references/confidence_and_limitations.md usando la herramienta Leer

Personalización de parámetros

Uso de configuración personalizada

Crea una configuración personalizada para casos de uso específicos:

# Copiar plantilla
cp assets/custom_inference_config.yaml my_config.yaml

# Editar parámetros (ver plantilla para ajustes preestablecidos)
# Luego ejecutar con configuración personalizada
python -m inference \
  --config my_config.yaml \
  --protein_ligand_csv input.csv \
  --out_dir results/

Parámetros clave para ajustar

Densidad de muestreo:

• samples_per_complex: 10 → Aumentar a 20-40 para casos difíciles
• Más muestras = mejor cobertura pero mayor tiempo de ejecución

Pasos de inferencia:

• inference_steps: 20 → Aumentar a 25-30 para mayor precisión
• Más pasos = potencialmente mejor calidad pero más lento

Parámetros de temperatura (controlan la diversidad):

• temp_sampling_tor: 7.04 → Aumentar para ligandos flexibles (8-10)
• temp_sampling_tor: 7.04 → Disminuir para ligandos rígidos (5-6)
• Temperatura más alta = poses más diversas

Ajustes preestablecidos disponibles en la plantilla:

1. Alta precisión: Más muestras + pasos, menor temperatura
2. Cribado rápido: Menos muestras, más rápido
3. Ligandos flexibles: Temperatura de torsión aumentada
4. Ligandos rígidos: Temperatura de torsión disminuida

Para obtener una referencia completa de parámetros: Lee references/parameters_reference.md usando la herramienta Leer

Técnicas avanzadas

Acoplamiento en conjunto (flexibilidad de la proteína)

Para proteínas con flexibilidad conocida, acopla a múltiples conformaciones:

# Crear CSV de conjunto
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)

Ejecuta el acoplamiento con muestreo aumentado:

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

Integración con funciones de puntuación

DiffDock genera poses; combínalo con otras herramientas para la afinidad:

GNINA (Puntuación rápida con red neuronal):

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

MM/GBSA (Más preciso, más lento): Usa AmberTools MMPBSA.py o gmx_MMPBSA después de la minimización de energía

Cálculos de energía libre (Más precisos): Usa OpenMM + OpenFE o GROMACS para cálculos FEP/TI

Flujo de trabajo recomendado:

1. DiffDock → Generar poses con puntuaciones de confianza
2. Inspección visual → Verificar plausibilidad estructural
3. GNINA o MM/GBSA → Reevaluar y clasificar por afinidad
4. Validación experimental → Ensayos bioquímicos

Limitaciones y alcance

DiffDock ESTÁ DISEÑADO PARA:

• Ligandos de moléculas pequeñas (típicamente 100-1000 Da)
• Compuestos orgánicos similares a fármacos
• Péptidos pequeños (<20 residuos)
• Proteínas de cadena única o múltiple

DiffDock NO ESTÁ DISEÑADO PARA:

• Biomoléculas grandes (acoplamiento proteína-proteína) → Usa DiffDock-PP o AlphaFold-Multimer
• Péptidos grandes (>20 residuos) → Usa métodos alternativos
• Acoplamiento covalente → Usa herramientas especializadas de acoplamiento covalente
• Predicción de afinidad de unión → Combínalo con funciones de puntuación
• Proteínas de membrana → No entrenado específicamente, úsalo con precaución

Para limitaciones completas: Lee references/confidence_and_limitations.md usando la herramienta Leer

Solución de problemas

Problemas comunes

Problema: Puntuaciones de confianza bajas en todas las predicciones

• Causa: Ligandos grandes/inusuales, sitio de unión poco claro, flexibilidad de la proteína
• Solución: Aumenta samples_per_complex (20-40), prueba el acoplamiento en conjunto, valida la estructura de la proteína

Problema: Errores de memoria insuficiente

• Causa: Memoria GPU insuficiente para el tamaño del lote
• Solución: Reduce --batch_size 2 o procesa menos complejos a la vez

Problema: Rendimiento lento

• Causa: Ejecutándose en CPU en lugar de GPU
• Solución: Verifica CUDA con python -c "import torch; print(torch.cuda.is_available())", usa GPU

Problema: Poses de unión no realistas

• Causa: Mala preparación de la proteína, ligando demasiado grande, sitio de unión incorrecto
• Solución: Verifica la proteína en busca de residuos faltantes, elimina aguas lejanas, considera especificar el sitio de unión

Problema: Errores de "Módulo no encontrado"

• Causa: Dependencias faltantes o entorno incorrecto
• Solución: Ejecuta python scripts/setup_check.py para diagnosticar

Optimización del rendimiento

Para obtener los mejores resultados:

1. Usa GPU (esencial para uso práctico)
2. Precalcula incrustaciones ESM para uso repetido de proteínas
3. Procesa múltiples complejos juntos por lotes
4. Comienza con parámetros predeterminados, luego ajusta si es necesario
5. Valida las estructuras de las proteínas (resuelve residuos faltantes)
6. Usa SMILES canónicos para ligandos

Interfaz gráfica de usuario

Para uso interactivo, inicia la interfaz web:

python app/main.py
# Navega a http://localhost:7860

O usa la demostración en línea sin instalación:

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

Recursos

Scripts auxiliares (scripts/)

prepare_batch_csv.py: Crear y validar archivos CSV de entrada por lotes

• Crear plantillas con entradas de ejemplo
• Validar rutas de archivos y cadenas SMILES
• Verificar columnas requeridas y problemas de formato

analyze_results.py: Analizar puntuaciones de confianza y clasificar predicciones

• Analizar resultados de ejecuciones individuales o por lotes
• Generar resúmenes estadísticos
• Exportar a CSV para análisis posteriores
• Identificar las mejores predicciones entre complejos

setup_check.py: Verificar la configuración del entorno de DiffDock

• Verificar la versión de Python y las dependencias
• Verificar la disponibilidad de PyTorch y CUDA
• Probar la instalación de RDKit y PyTorch Geometric
• Proporcionar instrucciones de instalación si es necesario

Documentación de referencia (references/)

parameters_reference.md: Documentación completa de parámetros

• Todas las opciones de línea de comandos y parámetros de configuración
• Valores predeterminados y rangos aceptables
• Parámetros de temperatura para controlar la diversidad
• Ubicaciones de los puntos de control del modelo y banderas de versión

Lee este archivo cuando los usuarios necesiten:

• Explicaciones detalladas de los parámetros
• Orientación para el ajuste fino de sistemas específicos
• Estrategias de muestreo alternativas

confidence_and_limitations.md: Interpretación de la puntuación de confianza y limitaciones de la herramienta

• Interpretación detallada de la puntuación de confianza
• Cuándo confiar en las predicciones
• Alcance y limitaciones de DiffDock
• Integración con herramientas complementarias
• Solución de problemas de calidad de predicción

Lee este archivo cuando los usuarios necesiten:

• Ayuda para interpretar las puntuaciones de confianza
• Entender cuándo NO usar DiffDock
• Orientación sobre la combinación con otras herramientas
• Estrategias de validación

workflows_examples.md: Ejemplos completos de flujos de trabajo

• Instrucciones detalladas de instalación
• Ejemplos paso a paso para todos los flujos de trabajo
• Patrones de integración avanzados
• Solución de problemas comunes
• Mejores prácticas y consejos de optimización

Lee este archivo cuando los usuarios necesiten:

• Ejemplos completos de flujos de trabajo con código
• Integración con GNINA, OpenMM u otras herramientas
• Flujos de trabajo de cribado virtual
• Procedimientos de acoplamiento en conjunto

Activos (assets/)

batch_template.csv: Plantilla de entrada por lotes para flujos de trabajo de acoplamiento múltiple

• Columnas predefinidas: complex_name, protein_path, ligand_description, protein_sequence
• Entradas de ejemplo para diferentes formatos de entrada
• Listo para usar con el comando --protein_ligand_csv

custom_inference_config.yaml: Plantilla de configuración personalizada con ajustes preestablecidos

• Ajustes preestablecidos: Alta precisión, cribado rápido, ligandos flexibles/ rígidos
• Parámetros documentados con valores predeterminados y rangos
• Secciones de comentarios para una personalización guiada
• Listo para usar con el comando --config

Ejemplos de acoplamiento (examples/)

Esta carpeta contiene ejemplos de PDB y SDF para probar DiffDock:

examples/
├── 1a42_complex/
│   ├── 1a42_protein.pdb
│   └── 1a42_ligand.sdf
├── 1a4k_complex/
│   ├── 1a4k_protein.pdb
│   └── 1a4k_ligand.sdf
└── 1a4o_complex/
    ├── 1a4o_protein.pdb
    └── 1a4o_ligand.sdf

Ejemplo de uso:

python -m inference \
  --config default_inference_args.yaml \
  --protein_path examples/1a42_complex/1a42_protein.pdb \
  --ligand_description examples/1a42_complex/1a42_ligand.sdf \
  --out_dir results/example_1a42/