@synsci/cli-darwin-arm64 1.1.76 → 1.1.78

package/bin/skills/diffdock/references/confidence_and_limitations.md

@@ -0,0 +1,182 @@
+# DiffDock Confidence Scores and Limitations
+
+This document provides detailed guidance on interpreting DiffDock confidence scores and understanding the tool's limitations.
+
+## Confidence Score Interpretation
+
+DiffDock generates a confidence score for each predicted binding pose. This score indicates the model's certainty about the prediction.
+
+### Score Ranges
+
+| Score Range | Confidence Level | Interpretation |
+|------------|------------------|----------------|
+| **> 0** | High confidence | Strong prediction, likely accurate binding pose |
+| **-1.5 to 0** | Moderate confidence | Reasonable prediction, may need validation |
+| **< -1.5** | Low confidence | Uncertain prediction, requires careful validation |
+
+### Important Notes on Confidence Scores
+
+1. **Not Binding Affinity**: Confidence scores reflect prediction certainty, NOT binding affinity strength
+   - High confidence = model is confident about the structure
+   - Does NOT indicate strong/weak binding affinity
+
+2. **Context-Dependent**: Confidence scores should be adjusted based on system complexity:
+   - **Lower expectations** for:
+     - Large ligands (>500 Da)
+     - Protein complexes with many chains
+     - Unbound protein conformations (may require conformational changes)
+     - Novel protein families not well-represented in training data
+
+   - **Higher expectations** for:
+     - Drug-like small molecules (150-500 Da)
+     - Single-chain proteins or well-defined binding sites
+     - Proteins similar to those in training data (PDBBind, BindingMOAD)
+
+3. **Multiple Predictions**: DiffDock generates multiple samples per complex (default: 10)
+   - Review top-ranked predictions (by confidence)
+   - Consider clustering similar poses
+   - High-confidence consensus across multiple samples strengthens prediction
+
+## What DiffDock Predicts
+
+### ✅ DiffDock DOES Predict
+- **Binding poses**: 3D spatial orientation of ligand in protein binding site
+- **Confidence scores**: Model's certainty about predictions
+- **Multiple conformations**: Various possible binding modes
+
+### ❌ DiffDock DOES NOT Predict
+- **Binding affinity**: Strength of protein-ligand interaction (ΔG, Kd, Ki)
+- **Binding kinetics**: On/off rates, residence time
+- **ADMET properties**: Absorption, distribution, metabolism, excretion, toxicity
+- **Selectivity**: Relative binding to different targets
+
+## Scope and Limitations
+
+### Designed For
+- **Small molecule docking**: Organic compounds typically 100-1000 Da
+- **Protein targets**: Single or multi-chain proteins
+- **Small peptides**: Short peptide ligands (< ~20 residues)
+- **Small nucleic acids**: Short oligonucleotides
+
+### NOT Designed For
+- **Large biomolecules**: Full protein-protein interactions
+  - Use DiffDock-PP, AlphaFold-Multimer, or RoseTTAFold2NA instead
+- **Large peptides/proteins**: >20 residues as ligands
+- **Covalent docking**: Irreversible covalent bond formation
+- **Metalloprotein specifics**: May not accurately handle metal coordination
+- **Membrane proteins**: Not specifically trained on membrane-embedded proteins
+
+### Training Data Considerations
+
+DiffDock was trained on:
+- **PDBBind**: Diverse protein-ligand complexes
+- **BindingMOAD**: Multi-domain protein structures
+
+**Implications**:
+- Best performance on proteins/ligands similar to training data
+- May underperform on:
+  - Novel protein families
+  - Unusual ligand chemotypes
+  - Allosteric sites not well-represented in training data
+
+## Validation and Complementary Tools
+
+### Recommended Workflow
+
+1. **Generate poses with DiffDock**
+   - Use confidence scores for initial ranking
+   - Consider multiple high-confidence predictions
+
+2. **Visual Inspection**
+   - Examine protein-ligand interactions in molecular viewer
+   - Check for reasonable:
+     - Hydrogen bonds
+     - Hydrophobic interactions
+     - Steric complementarity
+     - Electrostatic interactions
+
+3. **Scoring and Refinement** (choose one or more):
+   - **GNINA**: Deep learning-based scoring function
+   - **Molecular mechanics**: Energy minimization and refinement
+   - **MM/GBSA or MM/PBSA**: Binding free energy estimation
+   - **Free energy calculations**: FEP or TI for accurate affinity prediction
+
+4. **Experimental Validation**
+   - Biochemical assays (IC50, Kd measurements)
+   - Structural validation (X-ray crystallography, cryo-EM)
+
+### Tools for Binding Affinity Assessment
+
+DiffDock should be combined with these tools for affinity prediction:
+
+- **GNINA**: Fast, accurate scoring function
+  - Github: github.com/gnina/gnina
+
+- **AutoDock Vina**: Classical docking and scoring
+  - Website: vina.scripps.edu
+
+- **Free Energy Calculations**:
+  - OpenMM + OpenFE
+  - GROMACS + ABFE/RBFE protocols
+
+- **MM/GBSA Tools**:
+  - MMPBSA.py (AmberTools)
+  - gmx_MMPBSA
+
+## Performance Optimization
+
+### For Best Results
+
+1. **Protein Preparation**:
+   - Remove water molecules far from binding site
+   - Resolve missing residues if possible
+   - Consider protonation states at physiological pH
+
+2. **Ligand Input**:
+   - Provide reasonable 3D conformers when using structure files
+   - Use canonical SMILES for consistent results
+   - Pre-process with RDKit if needed
+
+3. **Computational Resources**:
+   - GPU strongly recommended (10-100x speedup)
+   - First run pre-computes lookup tables (takes a few minutes)
+   - Batch processing more efficient than single predictions
+
+4. **Parameter Tuning**:
+   - Increase `samples_per_complex` for difficult cases (20-40)
+   - Adjust temperature parameters for diversity/accuracy trade-off
+   - Use pre-computed ESM embeddings for repeated predictions
+
+## Common Issues and Troubleshooting
+
+### Low Confidence Scores
+- **Large/flexible ligands**: Consider splitting into fragments or use alternative methods
+- **Multiple binding sites**: May predict multiple locations with distributed confidence
+- **Protein flexibility**: Consider using ensemble of protein conformations
+
+### Unrealistic Predictions
+- **Clashes**: May indicate need for protein preparation or refinement
+- **Surface binding**: Check if true binding site is blocked or unclear
+- **Unusual poses**: Consider increasing samples to explore more conformations
+
+### Slow Performance
+- **Use GPU**: Essential for reasonable runtime
+- **Pre-compute embeddings**: Reuse ESM embeddings for same protein
+- **Batch processing**: More efficient than sequential individual predictions
+- **Reduce samples**: Lower `samples_per_complex` for quick screening
+
+## Citation and Further Reading
+
+For methodology details and benchmarking results, see:
+
+1. **Original DiffDock Paper** (ICLR 2023):
+   - "DiffDock: Diffusion Steps, Twists, and Turns for Molecular Docking"
+   - Corso et al., arXiv:2210.01776
+
+2. **DiffDock-L Paper** (2024):
+   - Enhanced model with improved generalization
+   - Stärk et al., arXiv:2402.18396
+
+3. **PoseBusters Benchmark**:
+   - Rigorous docking evaluation framework
+   - Used for DiffDock validation

package/bin/skills/diffdock/references/parameters_reference.md

@@ -0,0 +1,163 @@
+# DiffDock Configuration Parameters Reference
+
+This document provides comprehensive details on all DiffDock configuration parameters and command-line options.
+
+## Model & Checkpoint Settings
+
+### Model Paths
+- **`--model_dir`**: Directory containing the score model checkpoint
+  - Default: `./workdir/v1.1/score_model`
+  - DiffDock-L model (current default)
+
+- **`--confidence_model_dir`**: Directory containing the confidence model checkpoint
+  - Default: `./workdir/v1.1/confidence_model`
+
+- **`--ckpt`**: Name of the score model checkpoint file
+  - Default: `best_ema_inference_epoch_model.pt`
+
+- **`--confidence_ckpt`**: Name of the confidence model checkpoint file
+  - Default: `best_model_epoch75.pt`
+
+### Model Version Flags
+- **`--old_score_model`**: Use original DiffDock model instead of DiffDock-L
+  - Default: `false` (uses DiffDock-L)
+
+- **`--old_filtering_model`**: Use legacy confidence filtering approach
+  - Default: `true`
+
+## Input/Output Options
+
+### Input Specification
+- **`--protein_path`**: Path to protein PDB file
+  - Example: `--protein_path protein.pdb`
+  - Alternative to `--protein_sequence`
+
+- **`--protein_sequence`**: Amino acid sequence for ESMFold folding
+  - Automatically generates protein structure from sequence
+  - Alternative to `--protein_path`
+
+- **`--ligand`**: Ligand specification (SMILES string or file path)
+  - SMILES string: `--ligand "COc(cc1)ccc1C#N"`
+  - File path: `--ligand ligand.sdf` or `.mol2`
+
+- **`--protein_ligand_csv`**: CSV file for batch processing
+  - Required columns: `complex_name`, `protein_path`, `ligand_description`, `protein_sequence`
+  - Example: `--protein_ligand_csv data/protein_ligand_example.csv`
+
+### Output Control
+- **`--out_dir`**: Output directory for predictions
+  - Example: `--out_dir results/user_predictions/`
+
+- **`--save_visualisation`**: Export predicted molecules as SDF files
+  - Enables visualization of results
+
+## Inference Parameters
+
+### Diffusion Steps
+- **`--inference_steps`**: Number of planned inference iterations
+  - Default: `20`
+  - Higher values may improve accuracy but increase runtime
+
+- **`--actual_steps`**: Actual diffusion steps executed
+  - Default: `19`
+
+- **`--no_final_step_noise`**: Omit noise at the final diffusion step
+  - Default: `true`
+
+### Sampling Settings
+- **`--samples_per_complex`**: Number of samples to generate per complex
+  - Default: `10`
+  - More samples provide better coverage but increase computation
+
+- **`--sigma_schedule`**: Noise schedule type
+  - Default: `expbeta` (exponential-beta)
+
+- **`--initial_noise_std_proportion`**: Initial noise standard deviation scaling
+  - Default: `1.46`
+
+### Temperature Parameters
+
+#### Sampling Temperatures (Controls diversity of predictions)
+- **`--temp_sampling_tr`**: Translation sampling temperature
+  - Default: `1.17`
+
+- **`--temp_sampling_rot`**: Rotation sampling temperature
+  - Default: `2.06`
+
+- **`--temp_sampling_tor`**: Torsion sampling temperature
+  - Default: `7.04`
+
+#### Psi Angle Temperatures
+- **`--temp_psi_tr`**: Translation psi temperature
+  - Default: `0.73`
+
+- **`--temp_psi_rot`**: Rotation psi temperature
+  - Default: `0.90`
+
+- **`--temp_psi_tor`**: Torsion psi temperature
+  - Default: `0.59`
+
+#### Sigma Data Temperatures
+- **`--temp_sigma_data_tr`**: Translation data distribution scaling
+  - Default: `0.93`
+
+- **`--temp_sigma_data_rot`**: Rotation data distribution scaling
+  - Default: `0.75`
+
+- **`--temp_sigma_data_tor`**: Torsion data distribution scaling
+  - Default: `0.69`
+
+## Processing Options
+
+### Performance
+- **`--batch_size`**: Processing batch size
+  - Default: `10`
+  - Larger values increase throughput but require more memory
+
+- **`--tqdm`**: Enable progress bar visualization
+  - Useful for monitoring long-running jobs
+
+### Protein Structure
+- **`--chain_cutoff`**: Maximum number of protein chains to process
+  - Example: `--chain_cutoff 10`
+  - Useful for large multi-chain complexes
+
+- **`--esm_embeddings_path`**: Path to pre-computed ESM2 protein embeddings
+  - Speeds up inference by reusing embeddings
+  - Optional optimization
+
+### Dataset Options
+- **`--split`**: Dataset split to use (train/test/val)
+  - Used for evaluation on standard benchmarks
+
+## Advanced Flags
+
+### Debugging & Testing
+- **`--no_model`**: Disable model inference (debugging)
+  - Default: `false`
+
+- **`--no_random`**: Disable randomization
+  - Default: `false`
+  - Useful for reproducibility testing
+
+### Alternative Sampling
+- **`--ode`**: Use ODE solver instead of SDE
+  - Default: `false`
+  - Alternative sampling approach
+
+- **`--different_schedules`**: Use different noise schedules per component
+  - Default: `false`
+
+### Error Handling
+- **`--limit_failures`**: Maximum allowed failures before stopping
+  - Default: `5`
+
+## Configuration File
+
+All parameters can be specified in a YAML configuration file (typically `default_inference_args.yaml`) or overridden via command line:
+
+```bash
+python -m inference --config default_inference_args.yaml --samples_per_complex 20
+```
+
+Command-line arguments take precedence over configuration file values.