alterlab-diffdock
Predicts protein-ligand binding poses with DiffDock diffusion-based molecular docking from PDB structures and SMILES, producing pose confidence scores for virtual screening and structure-based drug design. Use when docking ligands into a protein, generating binding poses, or scre
Install
npx skills add https://github.com/AlterLab-IEU/AlterLab-Academic-Skills/tree/main/skills/cheminformatics/alterlab-diffdock
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alterlab-ieu-alterlab-academic-skills@llmmart
git clone https://github.com/AlterLab-IEU/AlterLab-Academic-Skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole alterlab-ieu/alterlab-academic-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
DiffDock: Molecular Docking with Diffusion Models
Overview
DiffDock is a diffusion-based deep learning tool for molecular docking that predicts 3D binding poses of small molecule ligands to protein targets. The repository's default model is DiffDock-L (Feb 2024); it is widely used for blind docking, though co-folding models (Boltz-2, Chai-1) and physics-based rescoring are now common complements, and predicted poses should be checked for physical validity (e.g. with PoseBusters).
Core Capabilities:
- Predict ligand binding poses with high accuracy using deep learning
- Support protein structures (PDB files) or sequences (via ESMFold)
- Process single complexes or batch virtual screening campaigns
- Generate confidence scores to assess prediction reliability
- Handle diverse ligand inputs (SMILES, SDF, MOL2)
Key Distinction: DiffDock predicts binding poses (3D structure) and confidence (prediction certainty), NOT binding affinity (ΔG, Kd). Always combine with scoring functions (GNINA, MM/GBSA) for affinity assessment.
When to Use This Skill
This skill should be used when:
- "Dock this ligand to a protein" or "predict binding pose"
- "Run molecular docking" or "perform protein-ligand docking"
- "Virtual screening" or "screen compound library"
- "Where does this molecule bind?" or "predict binding site"
- Structure-based drug design or lead optimization tasks
- Tasks involving PDB files + SMILES strings or ligand structures
- Batch docking of multiple protein-ligand pairs
Does NOT Trigger
| Scenario | Use Instead |
|---|---|
| Binding affinity / docking score on a cloud platform (AutoDock Vina) | alterlab-rowan |
| MD simulation of a complex, pose-stability / RMSD over a trajectory | alterlab-molecular-dynamics |
| Protein–protein or protein–nucleic-acid complex structure prediction | alterlab-boltz or alterlab-chai |
| Predicting the apo protein structure itself (no ligand) | alterlab-alphafold |
| Looking up measured protein–ligand affinities for the target | alterlab-bindingdb |
Hand-off rule. When the request matches a row above, open your answer by naming that skill by its exact id (for example alterlab-rowan) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.
Installation and Environment Setup
Check Environment Status
Before proceeding with DiffDock tasks, verify the environment setup:
# Use the provided setup checker
python scripts/setup_check.py
This script validates Python version, PyTorch with CUDA, PyTorch Geometric, RDKit, ESM, and other dependencies.
Installation Options
Option 1: Conda (Recommended)
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
Important Notes:
- GPU strongly recommended (10-100x speedup vs CPU)
- First run pre-computes SO(2)/SO(3) lookup tables (~2-5 minutes)
- Model checkpoints (~500MB) download automatically if not present
Core Workflows
Workflow 1: Single Protein-Ligand Docking
Use Case: Dock one ligand to one protein target
Input Requirements:
- Protein: PDB file OR amino acid sequence
- Ligand: SMILES string OR structure file (SDF/MOL2)
Command:
python -m inference \
--config default_inference_args.yaml \
--protein_path protein.pdb \
--ligand "CC(=O)Oc1ccccc1C(=O)O" \
--out_dir results/single_docking/
Alternative (protein sequence):
python -m inference \
--config default_inference_args.yaml \
--protein_sequence "MSKGEELFTGVVPILVELDGDVNGHKF..." \
--ligand ligand.sdf \
--out_dir results/sequence_docking/
Output Structure: DiffDock writes one subdirectory per complex (even for a single run), with the confidence embedded in each pose's filename:
results/single_docking/
└── complex_0/
├── rank1.sdf # Top pose (no score in name)
├── rank1_confidence-0.42.sdf # Same pose, confidence in filename
├── rank2_confidence-1.10.sdf # 2nd-ranked pose
├── ...
└── rank10_confidence-3.05.sdf # 10th pose (default: 10 samples)
There is no separate confidence_scores.txt; the confidence value is the confidenceN.NN suffix. Poses are ranked by descending confidence (rank1 = best).
Workflow 2: Batch Processing Multiple Complexes
Use Case: Dock multiple ligands to proteins, virtual screening campaigns
Step 1: Prepare Batch CSV
Use the provided script to create or validate batch input:
# 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 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,
Required Columns:
complex_name: Unique identifierprotein_path: PDB file path (leave empty if using sequence)ligand_description: SMILES string or ligand file pathprotein_sequence: Amino acid sequence (leave empty if using PDB)
Step 2: Run Batch Docking
python -m inference \
--config default_inference_args.yaml \
--protein_ligand_csv batch_input.csv \
--out_dir results/batch/ \
--batch_size 10
For Large Virtual Screening (>100 compounds):
Put every protein–ligand pair in one CSV and run a single inference call. At start-up
inference.py computes the ESM2 (esm2_t33_650M_UR50D) embeddings for all complexes in the
CSV in one batched pass and reuses them for the confidence model — there is no separate
pre-computation step and no --esm_embeddings_path flag for inference.
(datasets/esm_embedding_preparation.py / esm_embeddings_to_pt.py exist only for the
training/evaluation benchmarks.) Split very large libraries into several CSVs if GPU memory
or run time is a concern.
Config gotcha: values in the --config YAML are applied after the CLI flags and
override them. samples_per_complex, inference_steps, and the temp_* parameters are in
default_inference_args.yaml, so passing e.g. --samples_per_complex 20 alongside
--config default_inference_args.yaml has no effect — edit a copy of the YAML instead
(--batch_size is not in the default YAML, so the CLI flag works).
Workflow 3: Analyzing Results
After docking completes, analyze confidence scores and rank predictions:
# 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
The analysis script:
- Parses confidence scores from all predictions
- Classifies as High (>0), Moderate (-1.5 to 0), or Low (<-1.5)
- Ranks predictions within and across complexes
- Generates statistical summaries
- Exports results to CSV for downstream analysis
Confidence Score Interpretation
Understanding Scores:
| Score Range | Confidence Level | Interpretation |
|---|---|---|
| > 0 | High | Strong prediction, likely accurate |
| -1.5 to 0 | Moderate | Reasonable prediction, validate carefully |
| < -1.5 | Low | Uncertain prediction, requires validation |
Critical Notes:
- Confidence ≠ Affinity: High confidence means model certainty about structure, NOT strong binding
- Context Matters: Adjust expectations for:
- Large ligands (>500 Da): Lower confidence expected
- Multiple protein chains: May decrease confidence
- Novel protein families: May underperform
- Multiple Samples: Review top 3-5 predictions, look for consensus
For detailed guidance: Read references/confidence_and_limitations.md using the Read tool
Parameter Customization
Using Custom Configuration
Create custom configuration for specific use cases:
# 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/
Key Parameters to Adjust
Sampling Density:
samples_per_complex: 10→ Increase to 20-40 for difficult cases- More samples = better coverage but longer runtime
Inference Steps:
inference_steps: 20→ Increase to 25-30 for higher accuracy- More steps = potentially better quality but slower
Temperature Parameters (control diversity):
temp_sampling_tor: 7.04→ Increase for flexible ligands (8-10)temp_sampling_tor: 7.04→ Decrease for rigid ligands (5-6)- Higher temperature = more diverse poses
Presets Available in Template:
- High Accuracy: More samples + steps, lower temperature
- Fast Screening: Fewer samples, faster
- Flexible Ligands: Increased torsion temperature
- Rigid Ligands: Decreased torsion temperature
For complete parameter reference: Read references/parameters_reference.md using the Read tool
Advanced Techniques
Ensemble Docking (Protein Flexibility)
For proteins with known flexibility, dock to multiple conformations:
# 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)
Run docking with increased sampling (set samples_per_complex: 20 in a copy of the YAML —
a --samples_per_complex flag would be overwritten by the default config):
cp default_inference_args.yaml ensemble_args.yaml # edit: samples_per_complex: 20
python -m inference \
--config ensemble_args.yaml \
--protein_ligand_csv ensemble_input.csv \
--out_dir results/ensemble/
Integration with Scoring Functions
DiffDock generates poses; combine with other tools for affinity:
GNINA (Fast neural network scoring):
for pose in results/*.sdf; do
gnina -r protein.pdb -l "$pose" --score_only
done
MM/GBSA (More accurate, slower): Use AmberTools MMPBSA.py or gmx_MMPBSA after energy minimization
Free Energy Calculations (Most accurate): Use OpenMM + OpenFE or GROMACS for FEP/TI calculations
Recommended Workflow:
- DiffDock → Generate poses with confidence scores
- Visual inspection → Check structural plausibility
- GNINA or MM/GBSA → Rescore and rank by affinity
- Experimental validation → Biochemical assays
Limitations and Scope
DiffDock IS Designed For:
- Small molecule ligands (typically 100-1000 Da)
- Drug-like organic compounds
- Small peptides (<20 residues)
- Single or multi-chain proteins
DiffDock IS NOT Designed For:
- Large biomolecules (protein-protein docking) → Use DiffDock-PP or AlphaFold-Multimer
- Large peptides (>20 residues) → Use alternative methods
- Covalent docking → Use specialized covalent docking tools
- Binding affinity prediction → Combine with scoring functions
- Membrane proteins → Not specifically trained, use with caution
For complete limitations: Read references/confidence_and_limitations.md using the Read tool
Troubleshooting
Common Issues
Issue: Low confidence scores across all predictions
- Cause: Large/unusual ligands, unclear binding site, protein flexibility
- Solution: Increase
samples_per_complex(20-40), try ensemble docking, validate protein structure
Issue: Out of memory errors
- Cause: GPU memory insufficient for batch size
- Solution: Reduce
--batch_size 2or process fewer complexes at once
Issue: Slow performance
- Cause: Running on CPU instead of GPU
- Solution: Verify CUDA with
python -c "import torch; print(torch.cuda.is_available())", use GPU
Issue: Unrealistic binding poses
- Cause: Poor protein preparation, ligand too large, wrong binding site
- Solution: Check protein for missing residues, remove far waters, consider specifying binding site
Issue: "Module not found" errors
- Cause: Missing dependencies or wrong environment
- Solution: Run
python scripts/setup_check.pyto diagnose
Performance Optimization
For Best Results:
- Use GPU (essential for practical use)
- Pre-compute ESM embeddings for repeated protein use
- Batch process multiple complexes together
- Start with default parameters, then tune if needed
- Validate protein structures (resolve missing residues)
- Use canonical SMILES for ligands
Graphical User Interface
For interactive use, launch the web interface:
python app/main.py
# Navigate to http://localhost:7860
Or try the online demo (https://huggingface.co/spaces/reginabarzilaygroup/DiffDock-Web), though the Space is often down — prefer a local or Docker install for reliable runs.
Resources
Helper Scripts (scripts/)
prepare_batch_csv.py: Create and validate batch input CSV files
- Create templates with example entries
- Validate file paths and SMILES strings
- Check for required columns and format issues
analyze_results.py: Analyze confidence scores and rank predictions
- Parse results from single or batch runs
- Generate statistical summaries
- Export to CSV for downstream analysis
- Identify top predictions across complexes
setup_check.py: Verify DiffDock environment setup
- Check Python version and dependencies
- Verify PyTorch and CUDA availability
- Test RDKit and PyTorch Geometric installation
- Provide installation instructions if needed
Reference Documentation (references/)
parameters_reference.md: Complete parameter documentation
- All command-line options and configuration parameters
- Default values and acceptable ranges
- Temperature parameters for controlling diversity
- Model checkpoint locations and version flags
Read this file when users need:
- Detailed parameter explanations
- Fine-tuning guidance for specific systems
- Alternative sampling strategies
confidence_and_limitations.md: Confidence score interpretation and tool limitations
- Detailed confidence score interpretation
- When to trust predictions
- Scope and limitations of DiffDock
- Integration with complementary tools
- Troubleshooting prediction quality
Read this file when users need:
- Help interpreting confidence scores
- Understanding when NOT to use DiffDock
- Guidance on combining with other tools
- Validation strategies
workflows_examples.md: Comprehensive workflow examples
- Detailed installation instructions
- Step-by-step examples for all workflows
- Advanced integration patterns
- Troubleshooting common issues
- Best practices and optimization tips
Read this file when users need:
- Complete workflow examples with code
- Integration with GNINA, OpenMM, or other tools
- Virtual screening workflows
- Ensemble docking procedures
Assets (assets/)
batch_template.csv: Template for batch processing
- Pre-formatted CSV with required columns
- Example entries showing different input types
- Ready to customize with actual data
custom_inference_config.yaml: Configuration template
- Annotated YAML with all parameters
- Four preset configurations for common use cases
- Detailed comments explaining each parameter
- Ready to customize and use
Best Practices
- Always verify environment with
setup_check.pybefore starting large jobs - Validate batch CSVs with
prepare_batch_csv.pyto catch errors early - Start with defaults then tune parameters based on system-specific needs
- Generate multiple samples (10-40) for robust predictions
- Visual inspection of top poses before downstream analysis
- Combine with scoring functions for affinity assessment
- Use confidence scores for initial ranking, not final decisions
- Pre-compute embeddings for virtual screening campaigns
- Document parameters used for reproducibility
- Validate results experimentally when possible
Citations
When using DiffDock, cite the appropriate papers:
DiffDock-L (current default model):
Corso et al. (2024) "Deep Confident Steps to New Pockets: Strategies for Docking Generalization"
ICLR 2024, arXiv:2402.18396
Original DiffDock:
Corso et al. (2023) "DiffDock: Diffusion Steps, Twists, and Turns for Molecular Docking"
ICLR 2023, arXiv:2210.01776
Additional Resources
- GitHub Repository: https://github.com/gcorso/DiffDock
- Online Demo: https://huggingface.co/spaces/reginabarzilaygroup/DiffDock-Web
- DiffDock-L Paper: https://arxiv.org/abs/2402.18396
- Original Paper: https://arxiv.org/abs/2210.01776
Part of the AlterLab Academic Skills suite.
Files (alterlab-academic-skills)
-
assets
-
batch_template.csv 410 B · in bundle
-
custom_inference_config.yaml 2.8 KB
Loading…
-
-
evals
-
fixtures
-
protein.pdb 48.3 KB · in bundle
-
-
evals.json 5.2 KB
Loading…
-
-
references
-
confidence_and_limitations.md 6.8 KB
Loading… -
parameters_reference.md 5.3 KB
Loading… -
workflows_examples.md 10.9 KB
Loading…
-
-
scripts
-
analyze_results.py 10.2 KB
Loading… -
prepare_batch_csv.py 8.5 KB
Loading… -
setup_check.py 7.8 KB
Loading…
-
-
SKILL.md 18 KB
--- name: alterlab-diffdock description: Predicts protein-ligand binding poses with DiffDock diffusion-based molecular docking from PDB structures and SMILES, producing pose confidence scores for virtual screening and structure-based drug design. Use when docking ligands into a protein, generating binding poses, or screening compounds against a target; not for binding affinity prediction. Part of the AlterLab Academic Skills suite. license: MIT allowed-tools: Read Write Edit Bash(python:*) Bash(uv:*) compatibility: "Requires a local DiffDock checkout (gcorso/DiffDock via conda or Docker) and a GPU for practical use; no API key or account. The skill's helper scripts (scripts/) run standalone under python/uv." metadata: skill-author: AlterLab version: "1.0.1" last_updated: "2026-09-23" --- # DiffDock: Molecular Docking with Diffusion Models ## Overview DiffDock is a diffusion-based deep learning tool for molecular docking that predicts 3D binding poses of small molecule ligands to protein targets. The repository's default model is DiffDock-L (Feb 2024); it is widely used for blind docking, though co-folding models (Boltz-2, Chai-1) and physics-based rescoring are now common complements, and predicted poses should be checked for physical validity (e.g. with PoseBusters). **Core Capabilities:** - Predict ligand binding poses with high accuracy using deep learning - Support protein structures (PDB files) or sequences (via ESMFold) - Process single complexes or batch virtual screening campaigns - Generate confidence scores to assess prediction reliability - Handle diverse ligand inputs (SMILES, SDF, MOL2) **Key Distinction:** DiffDock predicts **binding poses** (3D structure) and **confidence** (prediction certainty), NOT binding affinity (ΔG, Kd). Always combine with scoring functions (GNINA, MM/GBSA) for affinity assessment. ## When to Use This Skill This skill should be used when: - "Dock this ligand to a protein" or "predict binding pose" - "Run molecular docking" or "perform protein-ligand docking" - "Virtual screening" or "screen compound library" - "Where does this molecule bind?" or "predict binding site" - Structure-based drug design or lead optimization tasks - Tasks involving PDB files + SMILES strings or ligand structures - Batch docking of multiple protein-ligand pairs ### Does NOT Trigger | Scenario | Use Instead | |----------|-------------| | Binding affinity / docking score on a cloud platform (AutoDock Vina) | `alterlab-rowan` | | MD simulation of a complex, pose-stability / RMSD over a trajectory | `alterlab-molecular-dynamics` | | Protein–protein or protein–nucleic-acid complex structure prediction | `alterlab-boltz` or `alterlab-chai` | | Predicting the apo protein structure itself (no ligand) | `alterlab-alphafold` | | Looking up measured protein–ligand affinities for the target | `alterlab-bindingdb` | **Hand-off rule.** When the request matches a row above, open your answer by naming that skill by its exact id (for example `alterlab-rowan`) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work. ## Installation and Environment Setup ### Check Environment Status Before proceeding with DiffDock tasks, verify the environment setup: ```bash # Use the provided setup checker python scripts/setup_check.py ``` This script validates Python version, PyTorch with CUDA, PyTorch Geometric, RDKit, ESM, and other dependencies. ### Installation Options **Option 1: Conda (Recommended)** ```bash git clone https://github.com/gcorso/DiffDock.git cd DiffDock conda env create --file environment.yml conda activate diffdock ``` **Option 2: Docker** ```bash docker pull rbgcsail/diffdock docker run -it --gpus all --entrypoint /bin/bash rbgcsail/diffdock micromamba activate diffdock ``` **Important Notes:** - GPU strongly recommended (10-100x speedup vs CPU) - First run pre-computes SO(2)/SO(3) lookup tables (~2-5 minutes) - Model checkpoints (~500MB) download automatically if not present ## Core Workflows ### Workflow 1: Single Protein-Ligand Docking **Use Case:** Dock one ligand to one protein target **Input Requirements:** - Protein: PDB file OR amino acid sequence - Ligand: SMILES string OR structure file (SDF/MOL2) **Command:** ```bash python -m inference \ --config default_inference_args.yaml \ --protein_path protein.pdb \ --ligand "CC(=O)Oc1ccccc1C(=O)O" \ --out_dir results/single_docking/ ``` **Alternative (protein sequence):** ```bash python -m inference \ --config default_inference_args.yaml \ --protein_sequence "MSKGEELFTGVVPILVELDGDVNGHKF..." \ --ligand ligand.sdf \ --out_dir results/sequence_docking/ ``` **Output Structure:** DiffDock writes one subdirectory per complex (even for a single run), with the confidence embedded in each pose's filename: ``` results/single_docking/ └── complex_0/ ├── rank1.sdf # Top pose (no score in name) ├── rank1_confidence-0.42.sdf # Same pose, confidence in filename ├── rank2_confidence-1.10.sdf # 2nd-ranked pose ├── ... └── rank10_confidence-3.05.sdf # 10th pose (default: 10 samples) ``` There is no separate `confidence_scores.txt`; the confidence value is the `confidenceN.NN` suffix. Poses are ranked by descending confidence (`rank1` = best). ### Workflow 2: Batch Processing Multiple Complexes **Use Case:** Dock multiple ligands to proteins, virtual screening campaigns **Step 1: Prepare Batch CSV** Use the provided script to create or validate batch input: ```bash # 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 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, ``` **Required Columns:** - `complex_name`: Unique identifier - `protein_path`: PDB file path (leave empty if using sequence) - `ligand_description`: SMILES string or ligand file path - `protein_sequence`: Amino acid sequence (leave empty if using PDB) **Step 2: Run Batch Docking** ```bash python -m inference \ --config default_inference_args.yaml \ --protein_ligand_csv batch_input.csv \ --out_dir results/batch/ \ --batch_size 10 ``` **For Large Virtual Screening (>100 compounds):** Put every protein–ligand pair in one CSV and run a single `inference` call. At start-up `inference.py` computes the ESM2 (`esm2_t33_650M_UR50D`) embeddings for all complexes in the CSV in one batched pass and reuses them for the confidence model — there is no separate pre-computation step and no `--esm_embeddings_path` flag for inference. (`datasets/esm_embedding_preparation.py` / `esm_embeddings_to_pt.py` exist only for the training/evaluation benchmarks.) Split very large libraries into several CSVs if GPU memory or run time is a concern. **Config gotcha:** values in the `--config` YAML are applied *after* the CLI flags and override them. `samples_per_complex`, `inference_steps`, and the `temp_*` parameters are in `default_inference_args.yaml`, so passing e.g. `--samples_per_complex 20` alongside `--config default_inference_args.yaml` has no effect — edit a copy of the YAML instead (`--batch_size` is not in the default YAML, so the CLI flag works). ### Workflow 3: Analyzing Results After docking completes, analyze confidence scores and rank predictions: ```bash # 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 ``` The analysis script: - Parses confidence scores from all predictions - Classifies as High (>0), Moderate (-1.5 to 0), or Low (<-1.5) - Ranks predictions within and across complexes - Generates statistical summaries - Exports results to CSV for downstream analysis ## Confidence Score Interpretation **Understanding Scores:** | Score Range | Confidence Level | Interpretation | |------------|------------------|----------------| | **> 0** | High | Strong prediction, likely accurate | | **-1.5 to 0** | Moderate | Reasonable prediction, validate carefully | | **< -1.5** | Low | Uncertain prediction, requires validation | **Critical Notes:** 1. **Confidence ≠ Affinity**: High confidence means model certainty about structure, NOT strong binding 2. **Context Matters**: Adjust expectations for: - Large ligands (>500 Da): Lower confidence expected - Multiple protein chains: May decrease confidence - Novel protein families: May underperform 3. **Multiple Samples**: Review top 3-5 predictions, look for consensus **For detailed guidance:** Read `references/confidence_and_limitations.md` using the Read tool ## Parameter Customization ### Using Custom Configuration Create custom configuration for specific use cases: ```bash # 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/ ``` ### Key Parameters to Adjust **Sampling Density:** - `samples_per_complex: 10` → Increase to 20-40 for difficult cases - More samples = better coverage but longer runtime **Inference Steps:** - `inference_steps: 20` → Increase to 25-30 for higher accuracy - More steps = potentially better quality but slower **Temperature Parameters (control diversity):** - `temp_sampling_tor: 7.04` → Increase for flexible ligands (8-10) - `temp_sampling_tor: 7.04` → Decrease for rigid ligands (5-6) - Higher temperature = more diverse poses **Presets Available in Template:** 1. High Accuracy: More samples + steps, lower temperature 2. Fast Screening: Fewer samples, faster 3. Flexible Ligands: Increased torsion temperature 4. Rigid Ligands: Decreased torsion temperature **For complete parameter reference:** Read `references/parameters_reference.md` using the Read tool ## Advanced Techniques ### Ensemble Docking (Protein Flexibility) For proteins with known flexibility, dock to multiple conformations: ```python # 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) ``` Run docking with increased sampling (set `samples_per_complex: 20` in a copy of the YAML — a `--samples_per_complex` flag would be overwritten by the default config): ```bash cp default_inference_args.yaml ensemble_args.yaml # edit: samples_per_complex: 20 python -m inference \ --config ensemble_args.yaml \ --protein_ligand_csv ensemble_input.csv \ --out_dir results/ensemble/ ``` ### Integration with Scoring Functions DiffDock generates poses; combine with other tools for affinity: **GNINA (Fast neural network scoring):** ```bash for pose in results/*.sdf; do gnina -r protein.pdb -l "$pose" --score_only done ``` **MM/GBSA (More accurate, slower):** Use AmberTools MMPBSA.py or gmx_MMPBSA after energy minimization **Free Energy Calculations (Most accurate):** Use OpenMM + OpenFE or GROMACS for FEP/TI calculations **Recommended Workflow:** 1. DiffDock → Generate poses with confidence scores 2. Visual inspection → Check structural plausibility 3. GNINA or MM/GBSA → Rescore and rank by affinity 4. Experimental validation → Biochemical assays ## Limitations and Scope **DiffDock IS Designed For:** - Small molecule ligands (typically 100-1000 Da) - Drug-like organic compounds - Small peptides (<20 residues) - Single or multi-chain proteins **DiffDock IS NOT Designed For:** - Large biomolecules (protein-protein docking) → Use DiffDock-PP or AlphaFold-Multimer - Large peptides (>20 residues) → Use alternative methods - Covalent docking → Use specialized covalent docking tools - Binding affinity prediction → Combine with scoring functions - Membrane proteins → Not specifically trained, use with caution **For complete limitations:** Read `references/confidence_and_limitations.md` using the Read tool ## Troubleshooting ### Common Issues **Issue: Low confidence scores across all predictions** - Cause: Large/unusual ligands, unclear binding site, protein flexibility - Solution: Increase `samples_per_complex` (20-40), try ensemble docking, validate protein structure **Issue: Out of memory errors** - Cause: GPU memory insufficient for batch size - Solution: Reduce `--batch_size 2` or process fewer complexes at once **Issue: Slow performance** - Cause: Running on CPU instead of GPU - Solution: Verify CUDA with `python -c "import torch; print(torch.cuda.is_available())"`, use GPU **Issue: Unrealistic binding poses** - Cause: Poor protein preparation, ligand too large, wrong binding site - Solution: Check protein for missing residues, remove far waters, consider specifying binding site **Issue: "Module not found" errors** - Cause: Missing dependencies or wrong environment - Solution: Run `python scripts/setup_check.py` to diagnose ### Performance Optimization **For Best Results:** 1. Use GPU (essential for practical use) 2. Pre-compute ESM embeddings for repeated protein use 3. Batch process multiple complexes together 4. Start with default parameters, then tune if needed 5. Validate protein structures (resolve missing residues) 6. Use canonical SMILES for ligands ## Graphical User Interface For interactive use, launch the web interface: ```bash python app/main.py # Navigate to http://localhost:7860 ``` Or try the online demo (https://huggingface.co/spaces/reginabarzilaygroup/DiffDock-Web), though the Space is often down — prefer a local or Docker install for reliable runs. ## Resources ### Helper Scripts (`scripts/`) **`prepare_batch_csv.py`**: Create and validate batch input CSV files - Create templates with example entries - Validate file paths and SMILES strings - Check for required columns and format issues **`analyze_results.py`**: Analyze confidence scores and rank predictions - Parse results from single or batch runs - Generate statistical summaries - Export to CSV for downstream analysis - Identify top predictions across complexes **`setup_check.py`**: Verify DiffDock environment setup - Check Python version and dependencies - Verify PyTorch and CUDA availability - Test RDKit and PyTorch Geometric installation - Provide installation instructions if needed ### Reference Documentation (`references/`) **`parameters_reference.md`**: Complete parameter documentation - All command-line options and configuration parameters - Default values and acceptable ranges - Temperature parameters for controlling diversity - Model checkpoint locations and version flags Read this file when users need: - Detailed parameter explanations - Fine-tuning guidance for specific systems - Alternative sampling strategies **`confidence_and_limitations.md`**: Confidence score interpretation and tool limitations - Detailed confidence score interpretation - When to trust predictions - Scope and limitations of DiffDock - Integration with complementary tools - Troubleshooting prediction quality Read this file when users need: - Help interpreting confidence scores - Understanding when NOT to use DiffDock - Guidance on combining with other tools - Validation strategies **`workflows_examples.md`**: Comprehensive workflow examples - Detailed installation instructions - Step-by-step examples for all workflows - Advanced integration patterns - Troubleshooting common issues - Best practices and optimization tips Read this file when users need: - Complete workflow examples with code - Integration with GNINA, OpenMM, or other tools - Virtual screening workflows - Ensemble docking procedures ### Assets (`assets/`) **`batch_template.csv`**: Template for batch processing - Pre-formatted CSV with required columns - Example entries showing different input types - Ready to customize with actual data **`custom_inference_config.yaml`**: Configuration template - Annotated YAML with all parameters - Four preset configurations for common use cases - Detailed comments explaining each parameter - Ready to customize and use ## Best Practices 1. **Always verify environment** with `setup_check.py` before starting large jobs 2. **Validate batch CSVs** with `prepare_batch_csv.py` to catch errors early 3. **Start with defaults** then tune parameters based on system-specific needs 4. **Generate multiple samples** (10-40) for robust predictions 5. **Visual inspection** of top poses before downstream analysis 6. **Combine with scoring** functions for affinity assessment 7. **Use confidence scores** for initial ranking, not final decisions 8. **Pre-compute embeddings** for virtual screening campaigns 9. **Document parameters** used for reproducibility 10. **Validate results** experimentally when possible ## Citations When using DiffDock, cite the appropriate papers: **DiffDock-L (current default model):** ``` Corso et al. (2024) "Deep Confident Steps to New Pockets: Strategies for Docking Generalization" ICLR 2024, arXiv:2402.18396 ``` **Original DiffDock:** ``` Corso et al. (2023) "DiffDock: Diffusion Steps, Twists, and Turns for Molecular Docking" ICLR 2023, arXiv:2210.01776 ``` ## Additional Resources - **GitHub Repository**: https://github.com/gcorso/DiffDock - **Online Demo**: https://huggingface.co/spaces/reginabarzilaygroup/DiffDock-Web - **DiffDock-L Paper**: https://arxiv.org/abs/2402.18396 - **Original Paper**: https://arxiv.org/abs/2210.01776 Part of the AlterLab Academic Skills suite.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.