diffdock

DiffDock: Docking Molecular com Modelos de Difusão

Visão Geral

DiffDock é uma ferramenta de aprendizado profundo baseada em difusão para docking molecular que prevê poses de ligação 3D de ligantes de pequenas moléculas a alvos proteicos. Ela representa o estado da arte em docking computacional, crucial para descoberta de medicamentos baseada em estrutura e biologia química.

Capacidades Principais:

• Prever poses de ligação de ligantes com alta precisão usando aprendizado profundo
• Suportar estruturas de proteínas (arquivos PDB) ou sequências (via ESMFold)
• Processar complexos únicos ou campanhas de triagem virtual em lote
• Gerar pontuações de confiança para avaliar a confiabilidade da predição
• Lidar com diversas entradas de ligantes (SMILES, SDF, MOL2)

Distinção Chave: DiffDock prevê poses de ligação (estrutura 3D) e confiança (certeza da predição), NÃO afinidade de ligação (ΔG, Kd). Sempre combine com funções de pontuação (GNINA, MM/GBSA) para avaliação de afinidade.

Quando Usar Esta Habilidade

Esta habilidade deve ser usada quando:

• "Dockar este ligante a uma proteína" ou "prever pose de ligação"
• "Executar docking molecular" ou "realizar docking proteína-ligante"
• "Triagem virtual" ou "triar biblioteca de compostos"
• "Onde esta molécula se liga?" ou "prever sítio de ligação"
• Tarefas de design de medicamentos baseado em estrutura ou otimização de líderes
• Tarefas envolvendo arquivos PDB + strings SMILES ou estruturas de ligantes
• Docking em lote de múltiplos pares proteína-ligante

Instalação e Configuração de Ambiente

Verificar Status do Ambiente

Antes de prosseguir com tarefas do DiffDock, verifique a configuração do ambiente:

# Use o verificador de configuração fornecido
python scripts/setup_check.py

Este script valida a versão do Python, PyTorch com CUDA, PyTorch Geometric, RDKit, ESM e outras dependências.

Opções de Instalação

Opção 1: Conda (Recomendado)

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

Opção 2: Docker

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

Notas Importantes:

• GPU fortemente recomendada (aceleração de 10-100x vs CPU)
• Primeira execução pré-computa tabelas de consulta SO(2)/SO(3) (~2-5 minutos)
• Checkpoints do modelo (~500MB) são baixados automaticamente se não presentes
• A versão upstream atual é DiffDock v1.1.3; DiffDock-L é a linha de modelo padrão em default_inference_args.yaml

Fluxos de Trabalho Principais

Fluxo de Trabalho 1: Docking de Único Proteína-Ligante

Caso de Uso: Dockar um ligante a um alvo proteico

Requisitos de Entrada:

• Proteína: arquivo PDB OU sequência de aminoácidos
• Ligante: string SMILES OU arquivo de estrutura (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 (sequência de proteína):

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

Estrutura de Saída:

results/single_docking/
└── complex_0/
    ├── rank1.sdf                    # Cópia de conveniência da pose melhor classificada
    ├── rank1_confidence0.87.sdf     # Pose melhor classificada com confiança no nome do arquivo
    ├── rank2_confidence0.42.sdf     # Segunda melhor pose classificada
    ├── ...
    └── rank10_confidence-1.23.sdf   # 10ª pose (padrão: 10 amostras)

O inference.py atual registra --ligand_description para execuções de complexo único. Alguns textos do README upstream ainda dizem --ligand; use --ligand_description a menos que seu checkout local suporte explicitamente um alias --ligand.

Fluxo de Trabalho 2: Processamento em Lote de Múltiplos Complexos

Caso de Uso: Dockar múltiplos ligantes a proteínas, campanhas de triagem virtual

Passo 1: Preparar CSV de Lote

Use o script fornecido para criar ou validar entrada em lote:

# Criar modelo
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,

Colunas Obrigatórias:

• complex_name: Identificador único
• protein_path: Caminho do arquivo PDB (deixe vazio se usar sequência)
• ligand_description: String SMILES ou caminho do arquivo de ligante
• protein_sequence: Sequência de aminoácidos (deixe vazio se usar PDB)

Passo 2: Executar Docking em Lote

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

Para Triagem Virtual Grande (>100 compostos):

Pré-compute embeddings de proteína para processamento mais rápido:

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

# Executar com embeddings pré-computados
python -m inference \
  --config default_inference_args.yaml \
  --protein_ligand_csv screening_input.csv \
  --esm_embeddings_path protein_embeddings.pt \
  --out_dir results/screening/

Fluxo de Trabalho 3: Analisando Resultados

Após o docking, analise as pontuações de confiança e classifique as predições:

# Analisar todos os resultados
python scripts/analyze_results.py results/batch/

# Mostrar top 5 por complexo
python scripts/analyze_results.py results/batch/ --top 5

# Filtrar por limite de confiança
python scripts/analyze_results.py results/batch/ --threshold 0.0

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

# Mostrar top 20 predições em todos os complexos
python scripts/analyze_results.py results/batch/ --best 20

O script de análise:

• Interpreta pontuações de confiança de todas as predições
• Classifica como Alto (>0), Moderado (-1.5 a 0) ou Baixo (<-1.5)
• Classifica predições dentro e entre complexos
• Gera resumos estatísticos
• Exporta resultados para CSV para análise downstream

Interpretação da Pontuação de Confiança

Entendendo as Pontuações:

Faixa de Pontuação	Nível de Confiança	Interpretação
> 0	Alto	Predição forte, provavelmente precisa
-1.5 a 0	Moderado	Predição razoável, validar com cuidado
< -1.5	Baixo	Predição incerta, requer validação

Notas Críticas:

1. Confiança ≠ Afinidade: Alta confiança significa certeza do modelo sobre a estrutura, NÃO ligação forte
2. Contexto Importa: Ajuste expectativas para:
   • Ligantes grandes (>500 Da): Confiança menor esperada
   • Múltiplas cadeias de proteína: Pode diminuir a confiança
   • Famílias de proteínas novas: Pode ter desempenho inferior
3. Múltiplas Amostras: Revise as 3-5 melhores predições, procure por consenso

Para orientação detalhada: Leia references/confidence_and_limitations.md usando a ferramenta Read

Personalização de Parâmetros

Usando Configuração Personalizada

Crie configuração personalizada para casos de uso específicos:

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

# Editar parâmetros (veja modelo para predefinições)
# Então execute com configuração personalizada
python -m inference \
  --config my_config.yaml \
  --protein_ligand_csv input.csv \
  --out_dir results/

Parâmetros Chave para Ajustar

Densidade de Amostragem:

• samples_per_complex: 10 → Aumente para 20-40 em casos difíceis
• Mais amostras = melhor cobertura, mas maior tempo de execução

Etapas de Inferência:

• inference_steps: 20 → Aumente para 25-30 para maior precisão
• Mais etapas = qualidade potencialmente melhor, mas mais lento

Parâmetros de Temperatura (controlam diversidade):

• temp_sampling_tor: 7.04 → Aumente para ligantes flexíveis (8-10)
• temp_sampling_tor: 7.04 → Diminua para ligantes rígidos (5-6)
• Temperatura mais alta = poses mais diversas

Predefinições Disponíveis no Modelo:

1. Alta Precisão: Mais amostras + etapas, temperatura mais baixa
2. Triagem Rápida: Menos amostras, mais rápido
3. Ligantes Flexíveis: Aumento da temperatura de torção
4. Ligantes Rígidos: Diminuição da temperatura de torção

Para referência completa de parâmetros: Leia references/parameters_reference.md usando a ferramenta Read

Técnicas Avançadas

Docking de Ensemble (Flexibilidade de Proteína)

Para proteínas com flexibilidade conhecida, docke em múltiplas conformações:

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

Execute o docking com amostragem aumentada:

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

Integração com Funções de Pontuação

DiffDock gera poses; combine com outras ferramentas para afinidade:

GNINA (Pontuação rápida de rede neural):

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

MM/GBSA (Mais preciso, mais lento): Use AmberTools MMPBSA.py ou gmx_MMPBSA após minimização de energia

Cálculos de Energia Livre (Mais precisos): Use OpenMM + OpenFE ou GROMACS para cálculos FEP/TI

Fluxo de Trabalho Recomendado:

1. DiffDock → Gere poses com pontuações de confiança
2. Inspeção visual → Verifique plausibilidade estrutural
3. GNINA ou MM/GBSA → Reclassifique e classifique por afinidade
4. Validação experimental → Ensaios bioquímicos

Limitações e Escopo

DiffDock É PROJETADO PARA:

• Ligantes de pequenas moléculas (tipicamente 100-1000 Da)
• Compostos orgânicos semelhantes a medicamentos
• Pequenos peptídeos (<20 resíduos)
• Proteínas de cadeia única ou múltipla

DiffDock NÃO É PROJETADO PARA:

• Grandes biomoléculas (docking proteína-proteína) → Use DiffDock-PP ou AlphaFold-Multimer
• Grandes peptídeos (>20 resíduos) → Use métodos alternativos
• Docking covalente → Use ferramentas especializadas de docking covalente
• Predição de afinidade de ligação → Combine com funções de pontuação
• Proteínas de membrana → Não especificamente treinado, use com cautela

Para limitações completas: Leia references/confidence_and_limitations.md usando a ferramenta Read

Solução de Problemas

Problemas Comuns

Problema: Pontuações de confiança baixas em todas as predições

• Causa: Ligantes grandes/incomuns, sítio de ligação não claro, flexibilidade da proteína
• Solução: Aumente samples_per_complex (20-40), tente docking de ensemble, valide a estrutura da proteína

Problema: Erros de memória insuficiente

• Causa: Memória GPU insuficiente para o tamanho do lote
• Solução: Reduza --batch_size 2 ou processe menos complexos de cada vez

Problema: Desempenho lento

• Causa: Executando em CPU em vez de GPU
• Solução: Verifique CUDA com python -c "import torch; print(torch.cuda.is_available())", use GPU

Problema: Poses de ligação irreais

• Causa: Preparação ruim da proteína, ligante muito grande, sítio de ligação errado
• Solução: Verifique a proteína para resíduos ausentes, remova águas distantes, considere especificar o sítio de ligação

Problema: Erros "Módulo não encontrado"

• Causa: Dependências ausentes ou ambiente errado
• Solução: Execute python scripts/setup_check.py para diagnosticar

Otimização de Desempenho

Para Melhores Resultados:

1. Use GPU (essencial para uso prático)
2. Pré-compute embeddings ESM para uso repetido de proteínas
3. Processe em lote múltiplos complexos juntos
4. Comece com parâmetros padrão, depois ajuste se necessário
5. Valide estruturas de proteínas (resolva resíduos ausentes)
6. Use SMILES canônicos para ligantes

Interface Gráfica do Usuário

Para uso interativo, inicie a interface web:

python app/main.py
# Navegue para http://localhost:7860

Ou use o demo online sem instalação:

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

Recursos

Scripts Auxiliares (scripts/)

prepare_batch_csv.py: Crie e valide arquivos CSV de entrada em lote

• Crie modelos com entradas de exemplo
• Valide caminhos de arquivos e strings SMILES
• Verifique se há colunas obrigatórias e problemas de formato

analyze_results.py: Analise pontuações de confiança e classifique predições

• Interprete resultados de execuções únicas ou em lote
• Gere resumos estatísticos
• Exporte para CSV para análise downstream
• Identifique as melhores predições entre complexos

setup_check.py: Verifique a configuração do ambiente DiffDock

• Verifique a versão do Python e dependências
• Verifique a disponibilidade do PyTorch e CUDA
• Teste a instalação do RDKit e PyTorch Geometric
• Forneça instruções de instalação se necessário

Documentação de Referência (references/)

parameters_reference.md: Documentação completa de parâmetros

• Todas as opções de linha de comando e parâmetros de configuração
• Valores padrão e faixas aceitáveis
• Parâmetros de temperatura para controlar diversidade
• Localizações de checkpoints do modelo e sinalizadores de versão

Leia este arquivo quando os usuários precisarem:

• Explicações detalhadas de parâmetros
• Orientação de ajuste fino para sistemas específicos
• Estratégias alternativas de amostragem

confidence_and_limitations.md: Interpretação de pontuação de confiança e limitações da ferramenta

• Interpretação detalhada da pontuação de confiança
• Quando confiar nas predições
• Escopo e limitações do DiffDock
• Integração com ferramentas complementares
• Solução de problemas de qualidade de predição

Leia este arquivo quando os usuários precisarem:

• Ajuda para interpretar pontuações de confiança
• Entender quando NÃO usar DiffDock
• Orientação sobre combinação com outras ferramentas
• Estratégias de validação

workflows_examples.md: Exemplos abrangentes de fluxos de trabalho

• Instruções detalhadas de instalação
• Exemplos passo a passo para todos os fluxos de trabalho
• Padrões avançados de integração
• Solução de problemas comuns
• Melhores práticas e dicas de otimização

Leia este arquivo quando os usuários precisarem:

• Exemplos completos de fluxo de trabalho com código
• Integração com GNINA, OpenMM ou outras ferramentas
• Fluxos de trabalho de triagem virtual
• Procedimentos de docking de ensemble

Ativos (assets/)

batch_template.csv: Modelo de arquivo CSV de triagem em lote. Útil para criar entradas em lote rapidamente. Contém entradas de exemplo e formatação correta.

custom_inference_config.yaml: Modelo de configuração personalizada para ajuste de parâmetros. Útil quando os parâmetros padrão precisam ser modificados para casos de uso específicos. Contém predefinições para diferentes cenários.

pkasolver_cache.tar.gz: Cache de pesos pré-treinados para o modelo pkasolver. Melhora o desempenho para cálculos de pKa quando usados com o DiffDock.