@saibolla/ada 0.1.2

package/skills/torchdrug/references/protein_modeling.md

@@ -0,0 +1,272 @@
+# Protein Modeling
+
+## Overview
+
+TorchDrug provides extensive support for protein-related tasks including sequence analysis, structure prediction, property prediction, and protein-protein interactions. Proteins are represented as graphs where nodes are amino acid residues and edges represent spatial or sequential relationships.
+
+## Available Datasets
+
+### Protein Function Prediction
+
+**Enzyme Function:**
+- **EnzymeCommission** (17,562 proteins): EC number classification (7 levels)
+- **BetaLactamase** (5,864 sequences): Enzyme activity prediction
+
+**Protein Characteristics:**
+- **Fluorescence** (54,025 sequences): GFP fluorescence intensity
+- **Stability** (53,614 sequences): Thermostability prediction
+- **Solubility** (62,478 sequences): Protein solubility classification
+- **BinaryLocalization** (22,168 proteins): Subcellular localization (membrane vs. soluble)
+- **SubcellularLocalization** (8,943 proteins): 10-class localization prediction
+
+**Gene Ontology:**
+- **GeneOntology** (46,796 proteins): GO term prediction across biological process, molecular function, and cellular component
+
+### Protein Structure Prediction
+
+- **Fold** (16,712 proteins): Structural fold classification (1,195 classes)
+- **SecondaryStructure** (8,678 proteins): 3-state or 8-state secondary structure prediction
+- **ContactPrediction** via ProteinNet: Residue-residue contact maps
+
+### Protein Interaction
+
+**Protein-Protein Interactions:**
+- **HumanPPI** (1,412 proteins, 6,584 interactions): Human protein interaction network
+- **YeastPPI** (2,018 proteins, 6,451 interactions): Yeast protein interaction network
+- **PPIAffinity** (2,156 protein pairs): Binding affinity measurements
+
+**Protein-Ligand Binding:**
+- **BindingDB** (~1.5M entries): Comprehensive binding affinity database
+- **PDBBind** (20,000+ complexes): 3D structure-based binding data
+  - Refined set: High-quality crystal structures
+  - Core set: Diverse benchmark set
+
+### Large-Scale Protein Databases
+
+- **AlphaFoldDB**: Access to 200M+ predicted protein structures
+- **ProteinNet**: Standardized dataset for structure prediction
+
+## Task Types
+
+### NodePropertyPrediction
+
+Predict properties at the residue (node) level, such as secondary structure or contact maps.
+
+**Use Cases:**
+- Secondary structure prediction (helix, sheet, coil)
+- Residue-level disorder prediction
+- Post-translational modification sites
+- Binding site prediction
+
+### PropertyPrediction
+
+Predict protein-level properties like function, stability, or localization.
+
+**Use Cases:**
+- Enzyme function classification
+- Subcellular localization
+- Protein stability prediction
+- Gene ontology term prediction
+
+### InteractionPrediction
+
+Predict interactions between protein pairs or protein-ligand pairs.
+
+**Key Features:**
+- Handles both sequence and structure inputs
+- Supports symmetric (PPI) and asymmetric (protein-ligand) interactions
+- Multiple negative sampling strategies
+
+### ContactPrediction
+
+Specialized task for predicting spatial proximity between residues in folded structures.
+
+**Applications:**
+- Structure prediction from sequence
+- Protein folding pathway analysis
+- Validation of predicted structures
+
+## Protein Representation Models
+
+### Sequence-Based Models
+
+**ESM (Evolutionary Scale Modeling):**
+- Pre-trained transformer model on 250M sequences
+- State-of-the-art for sequence-only tasks
+- Available in multiple sizes (ESM-1b, ESM-2)
+- Captures evolutionary and structural information
+
+**ProteinBERT:**
+- BERT-style masked language model
+- Pre-trained on UniProt sequences
+- Good for transfer learning
+
+**ProteinLSTM:**
+- Bidirectional LSTM for sequence encoding
+- Lightweight and fast
+- Good baseline for sequence tasks
+
+**ProteinCNN / ProteinResNet:**
+- Convolutional architectures
+- Capture local sequence patterns
+- Faster than transformer models
+
+### Structure-Based Models
+
+**GearNet (Geometry-Aware Relational Graph Network):**
+- Incorporates 3D geometric information
+- Edge types based on sequential, radius, and K-nearest neighbors
+- State-of-the-art for structure-based tasks
+- Supports both backbone and full-atom representations
+
+**GCN/GAT/GIN on Protein Graphs:**
+- Standard GNN architectures adapted for proteins
+- Flexible edge definitions (sequence, spatial, contact)
+
+**SchNet:**
+- Continuous-filter convolutions
+- Handles 3D coordinates directly
+- Good for structure prediction and protein-ligand binding
+
+### Feature-Based Models
+
+**Statistic Features:**
+- Amino acid composition
+- Sequence length statistics
+- Motif counts
+
+**Physicochemical Features:**
+- Hydrophobicity scales
+- Charge properties
+- Secondary structure propensity
+- Molecular weight, pI
+
+## Protein Graph Construction
+
+### Edge Types
+
+**Sequential Edges:**
+- Connect adjacent residues in sequence
+- Captures primary structure
+
+**Spatial Edges:**
+- K-nearest neighbors in 3D space
+- Radius cutoff (e.g., Cα atoms within 10Å)
+- Captures tertiary structure
+
+**Contact Edges:**
+- Based on heavy atom distances
+- Typically < 8Å threshold
+
+### Node Features
+
+**Residue Identity:**
+- One-hot encoding of 20 amino acids
+- Learned embeddings
+
+**Position Information:**
+- 3D coordinates (Cα, N, C, O)
+- Backbone angles (phi, psi, omega)
+- Relative spatial position encodings
+
+**Physicochemical Properties:**
+- Hydrophobicity
+- Charge
+- Size
+- Secondary structure
+
+## Training Workflows
+
+### Pre-training Strategies
+
+**Self-Supervised Pre-training:**
+- Masked residue prediction (like BERT)
+- Distance prediction between residues
+- Angle prediction (phi, psi, omega)
+- Dihedral angle prediction
+- Contact map prediction
+
+**Pre-trained Model Usage:**
+```python
+from torchdrug import models
+
+# Load pre-trained ESM
+model = models.ESM(path="esm1b_t33_650M_UR50S.pt")
+
+# Fine-tune on downstream task
+task = tasks.PropertyPrediction(
+    model, task=["stability"],
+    criterion="mse", metric=["mae", "rmse"]
+)
+```
+
+### Multi-Task Learning
+
+Train on multiple related tasks simultaneously:
+- Joint prediction of function, localization, and stability
+- Improves generalization and data efficiency
+- Shares representations across tasks
+
+### Best Practices
+
+**For Sequence-Only Tasks:**
+1. Start with pre-trained ESM or ProteinBERT
+2. Fine-tune with small learning rate (1e-5 to 1e-4)
+3. Use frozen embeddings for small datasets
+4. Apply dropout for regularization
+
+**For Structure-Based Tasks:**
+1. Use GearNet with multiple edge types
+2. Include geometric features (angles, dihedrals)
+3. Pre-train on large structure databases
+4. Use data augmentation (rotations, crops)
+
+**For Small Datasets:**
+1. Transfer learning from pre-trained models
+2. Multi-task learning with related tasks
+3. Data augmentation (sequence mutations, structure perturbations)
+4. Strong regularization (dropout, weight decay)
+
+## Common Use Cases
+
+### Enzyme Engineering
+- Predict enzyme activity from sequence
+- Design mutations to improve stability
+- Screen for desired catalytic properties
+
+### Antibody Design
+- Predict binding affinity
+- Optimize antibody sequences
+- Predict immunogenicity
+
+### Drug Target Identification
+- Predict protein function
+- Identify druggable sites
+- Analyze protein-ligand interactions
+
+### Protein Structure Prediction
+- Predict secondary structure from sequence
+- Generate contact maps for tertiary structure
+- Refine AlphaFold predictions
+
+## Integration with Other Tools
+
+### AlphaFold Integration
+
+Load AlphaFold-predicted structures:
+```python
+from torchdrug import data
+
+# Load AlphaFold structure
+protein = data.Protein.from_pdb("alphafold_structure.pdb")
+
+# Use in TorchDrug workflows
+```
+
+### ESMFold Integration
+
+Use ESMFold for structure prediction, then analyze with TorchDrug models.
+
+### Rosetta/PyRosetta
+
+Generate structures with Rosetta, import to TorchDrug for analysis.

package/skills/torchdrug/references/retrosynthesis.md

@@ -0,0 +1,436 @@
+# Retrosynthesis
+
+## Overview
+
+Retrosynthesis is the process of planning synthetic routes from target molecules back to commercially available starting materials. TorchDrug provides tools for learning-based retrosynthesis prediction, breaking down the complex task into manageable subtasks.
+
+## Available Datasets
+
+### USPTO-50K
+
+The standard benchmark dataset for retrosynthesis derived from US patent literature.
+
+**Statistics:**
+- 50,017 reaction examples
+- Single-step reactions
+- Filtered for quality and canonicalization
+- Contains atom mapping for reaction center identification
+
+**Reaction Types:**
+- Diverse organic reactions
+- Drug-like transformations
+- Well-balanced across common reaction classes
+
+**Data Splits:**
+- Training: ~40k reactions
+- Validation: ~5k reactions
+- Test: ~5k reactions
+
+**Format:**
+- Product → Reactants
+- SMILES representation
+- Atom-mapped reactions for training
+
+## Task Types
+
+TorchDrug decomposes retrosynthesis into a multi-step pipeline:
+
+### 1. CenterIdentification
+
+Identifies the reaction center - which bonds were formed/broken in the forward reaction.
+
+**Input:** Product molecule
+**Output:** Probability for each bond of being part of reaction center
+
+**Purpose:**
+- Locate where chemistry happened
+- Guide subsequent synthon generation
+- Reduce search space dramatically
+
+**Model Architecture:**
+- Graph neural network on product molecule
+- Edge-level classification
+- Attention mechanisms to highlight reactive regions
+
+**Evaluation Metrics:**
+- **Top-K Accuracy**: Correct reaction center in top K predictions
+- **Bond-level F1**: Precision and recall for bond predictions
+
+### 2. SynthonCompletion
+
+Given the product and identified reaction center, predict the reactant structures (synthons).
+
+**Input:**
+- Product molecule
+- Identified reaction center (broken/formed bonds)
+
+**Output:**
+- Predicted reactant molecules (synthons)
+
+**Process:**
+1. Break bonds at reaction center
+2. Modify atom environments (valence, charges)
+3. Determine leaving groups and protecting groups
+4. Generate complete reactant structures
+
+**Challenges:**
+- Multiple valid reactant sets
+- Stereospecificity
+- Atom environment changes (hybridization, charge)
+- Leaving group selection
+
+**Evaluation:**
+- **Exact Match**: Generated reactants exactly match ground truth
+- **Top-K Accuracy**: Correct reactants in top K predictions
+- **Chemical Validity**: Generated molecules are valid
+
+### 3. Retrosynthesis (End-to-End)
+
+Combines center identification and synthon completion into a unified pipeline.
+
+**Input:** Target product molecule
+**Output:** Ranked list of reactant sets (synthesis pathways)
+
+**Workflow:**
+1. Identify top-K reaction centers
+2. For each center, generate reactant candidates
+3. Rank combinations by model confidence
+4. Filter for commercial availability and feasibility
+
+**Advantages:**
+- Single model to train and deploy
+- Joint optimization of subtasks
+- Error propagation from center identification accounted for
+
+## Training Workflows
+
+### Basic Pipeline
+
+```python
+from torchdrug import datasets, models, tasks
+
+# Load dataset
+dataset = datasets.USPTO50k("~/retro-datasets/")
+
+# For center identification
+model_center = models.RGCN(
+    input_dim=dataset.node_feature_dim,
+    num_relation=dataset.num_bond_type,
+    hidden_dims=[256, 256, 256]
+)
+
+task_center = tasks.CenterIdentification(
+    model_center,
+    top_k=3  # Consider top 3 reaction centers
+)
+
+# For synthon completion
+model_synthon = models.GIN(
+    input_dim=dataset.node_feature_dim,
+    hidden_dims=[256, 256, 256]
+)
+
+task_synthon = tasks.SynthonCompletion(
+    model_synthon,
+    center_topk=3,  # Use top 3 from center identification
+    num_synthon_beam=5  # Beam search for synthon generation
+)
+
+# End-to-end
+task_retro = tasks.Retrosynthesis(
+    model=model_center,
+    synthon_model=model_synthon,
+    center_topk=5,
+    num_synthon_beam=10
+)
+```
+
+### Transfer Learning
+
+Pre-train on large reaction datasets (e.g., USPTO-full with 1M+ reactions), then fine-tune on specific reaction classes.
+
+**Benefits:**
+- Better generalization to rare reaction types
+- Improved performance on small datasets
+- Learn general reaction patterns
+
+### Multi-Task Learning
+
+Train jointly on:
+- Forward reaction prediction
+- Retrosynthesis
+- Reaction type classification
+- Yield prediction
+
+**Advantages:**
+- Shared representations of chemistry
+- Better sample efficiency
+- Improved robustness
+
+## Model Architectures
+
+### Graph Neural Networks
+
+**RGCN (Relational Graph Convolutional Network):**
+- Handles multiple bond types (single, double, triple, aromatic)
+- Edge-type-specific transformations
+- Good for reaction center identification
+
+**GIN (Graph Isomorphism Network):**
+- Powerful message passing
+- Captures structural patterns
+- Works well for synthon completion
+
+**GAT (Graph Attention Network):**
+- Attention weights highlight important atoms/bonds
+- Interpretable reaction center predictions
+- Flexible for various reaction types
+
+### Sequence-Based Models
+
+**Transformer Models:**
+- SMILES-to-SMILES translation
+- Can capture long-range dependencies
+- Require large datasets
+
+**LSTM/GRU:**
+- Sequence generation for reactants
+- Autoregressive decoding
+- Good for small molecules
+
+### Hybrid Approaches
+
+Combine graph and sequence representations:
+- Graph encoder for products
+- Sequence decoder for reactants
+- Best of both representations
+
+## Reaction Chemistry Considerations
+
+### Reaction Classes
+
+**Common Transformations:**
+- C-C bond formation (coupling, addition)
+- Functional group interconversions (oxidation, reduction)
+- Heterocycle synthesis (cyclizations)
+- Protection/deprotection
+- Aromatic substitutions
+
+**Rare Reactions:**
+- Novel coupling methods
+- Complex rearrangements
+- Multi-component reactions
+
+### Selectivity Issues
+
+**Regioselectivity:**
+- Which position reacts on molecule
+- Requires understanding of electronics and sterics
+
+**Stereoselectivity:**
+- Control of stereochemistry
+- Diastereoselectivity and enantioselectivity
+- Critical for drug synthesis
+
+**Chemoselectivity:**
+- Which functional group reacts
+- Requires protecting group strategies
+
+### Reaction Conditions
+
+While TorchDrug focuses on reaction connectivity, consider:
+- Temperature and pressure
+- Catalysts and reagents
+- Solvents
+- Reaction time
+- Work-up and purification
+
+## Multi-Step Synthesis Planning
+
+### Single-Step Retrosynthesis
+
+Predict immediate precursors for target molecule.
+
+**Use Case:**
+- Late-stage transformations
+- Simple molecules (1-2 steps from commercial)
+- Initial route scouting
+
+### Multi-Step Planning
+
+Recursively apply retrosynthesis to each predicted reactant until reaching commercial building blocks.
+
+**Tree Search Strategies:**
+
+**Breadth-First Search:**
+- Explore all routes to same depth
+- Find shortest routes
+- Memory intensive
+
+**Depth-First Search:**
+- Follow each route to completion
+- Memory efficient
+- May miss optimal routes
+
+**Monte Carlo Tree Search (MCTS):**
+- Balance exploration and exploitation
+- Guided by model confidence
+- State-of-the-art for multi-step planning
+
+**A\* Search:**
+- Heuristic-guided search
+- Optimizes for cost, complexity, or feasibility
+- Efficient for finding best routes
+
+### Route Scoring
+
+Rank synthetic routes by:
+1. **Number of Steps**: Fewer is better (efficiency)
+2. **Convergent vs Linear**: Convergent routes preferred
+3. **Commercial Availability**: How many steps to buyable compounds
+4. **Reaction Feasibility**: Likelihood each step works
+5. **Overall Yield**: Estimated end-to-end yield
+6. **Cost**: Reagents, labor, equipment
+7. **Green Chemistry**: Environmental impact, safety
+
+### Stopping Criteria
+
+Stop retrosynthesis when reaching:
+- **Commercial Compounds**: Available from vendors (e.g., Sigma-Aldrich, Enamine)
+- **Building Blocks**: Standard synthetic intermediates
+- **Max Depth**: e.g., 6-10 steps
+- **Low Confidence**: Model uncertainty too high
+
+## Validation and Filtering
+
+### Chemical Validity
+
+Check each predicted reaction:
+- Reactants are valid molecules
+- Reaction is chemically reasonable
+- Atom mapping is consistent
+- Stoichiometry balances
+
+### Synthetic Feasibility
+
+**Filters:**
+- Reaction precedent (literature examples)
+- Functional group compatibility
+- Typical reaction conditions
+- Expected yield ranges
+
+**Expert Systems:**
+- Rule-based validation (e.g., ARChem Route Designer)
+- Check for incompatible functional groups
+- Identify protection/deprotection needs
+
+### Commercial Availability
+
+**Databases:**
+- eMolecules: 10M+ commercial compounds
+- ZINC: Annotated with vendor info
+- Reaxys: Commercially available building blocks
+
+**Considerations:**
+- Cost per gram
+- Purity and quality
+- Lead time for delivery
+- Minimum order quantities
+
+## Integration with Other Tools
+
+### Reaction Prediction (Forward)
+
+Train forward reaction prediction models to validate retrosynthetic proposals:
+- Predict products from proposed reactants
+- Validate reaction feasibility
+- Estimate yields
+
+### Retrosynthesis Software
+
+**Integration with:**
+- SciFinder (CAS)
+- Reaxys (Elsevier)
+- ARChem Route Designer
+- IBM RXN for Chemistry
+
+**TorchDrug as Component:**
+- Use TorchDrug models within larger planning systems
+- Combine ML predictions with rule-based systems
+- Hybrid AI + expert system approaches
+
+### Experimental Validation
+
+**High-Throughput Screening:**
+- Rapid testing of predicted reactions
+- Automated synthesis platforms
+- Feedback loop to improve models
+
+**Robotic Synthesis:**
+- Automated execution of planned routes
+- Real-time optimization
+- Data generation for model improvement
+
+## Best Practices
+
+1. **Ensemble Predictions**: Use multiple models for robustness
+2. **Reaction Validation**: Always validate with chemistry rules
+3. **Commercial Check**: Verify building block availability early
+4. **Diversity**: Generate multiple diverse routes, not just top-1
+5. **Expert Review**: Have chemists evaluate proposed routes
+6. **Literature Search**: Check for precedents of key steps
+7. **Iterative Refinement**: Update models with experimental feedback
+8. **Interpretability**: Understand why model suggests each step
+9. **Edge Cases**: Handle unusual functional groups and scaffolds
+10. **Benchmarking**: Compare against known synthesis routes
+
+## Common Applications
+
+### Drug Synthesis Planning
+
+- Small molecule drugs
+- Natural product total synthesis
+- Late-stage functionalization strategies
+
+### Library Enumeration
+
+- Virtual library design
+- Retrosynthetic filtering of generated molecules
+- Prioritize synthesizable compounds
+
+### Process Chemistry
+
+- Route scouting for large-scale synthesis
+- Cost optimization
+- Green chemistry alternatives
+
+### Synthetic Method Development
+
+- Identify gaps in synthetic methodology
+- Guide development of new reactions
+- Expand retrosynthesis model capabilities
+
+## Challenges and Future Directions
+
+### Current Limitations
+
+- Limited to single-step predictions (most models)
+- Doesn't consider reaction conditions explicitly
+- Stereochemistry handling is challenging
+- Rare reaction types underrepresented
+
+### Active Research Areas
+
+- End-to-end multi-step planning
+- Incorporation of reaction conditions
+- Stereoselective retrosynthesis
+- Integration with robotics for closed-loop optimization
+- Semi-template methods (balance templates and templates-free)
+- Uncertainty quantification for predictions
+
+### Emerging Techniques
+
+- Large language models for chemistry (ChemGPT, MolT5)
+- Reinforcement learning for route optimization
+- Graph transformers for long-range interactions
+- Self-supervised pre-training on reaction databases