@synsci/cli-darwin-x64 1.1.97 → 1.1.99

package/bin/skills/torchdrug/references/datasets.md

@@ -1,380 +0,0 @@
-# Datasets Reference
-
-## Overview
-
-TorchDrug provides 40+ curated datasets across multiple domains: molecular property prediction, protein modeling, knowledge graph reasoning, and retrosynthesis. All datasets support lazy loading, automatic downloading, and customizable feature extraction.
-
-## Molecular Property Prediction Datasets
-
-### Drug Discovery Classification
-
-| Dataset | Size | Task | Classes | Description |
-|---------|------|------|---------|-------------|
-| **BACE** | 1,513 | Binary | 2 | β-secretase inhibition for Alzheimer's |
-| **BBBP** | 2,039 | Binary | 2 | Blood-brain barrier penetration |
-| **HIV** | 41,127 | Binary | 2 | Inhibition of HIV replication |
-| **ClinTox** | 1,478 | Multi-label | 2 | Clinical trial toxicity |
-| **SIDER** | 1,427 | Multi-label | 27 | Side effects by system organ class |
-| **Tox21** | 7,831 | Multi-label | 12 | Toxicity across 12 targets |
-| **ToxCast** | 8,576 | Multi-label | 617 | High-throughput toxicology |
-| **MUV** | 93,087 | Multi-label | 17 | Unbiased validation for screening |
-
-**Key Features:**
-- All use scaffold splits for realistic evaluation
-- Binary classification metrics: AUROC, AUPRC
-- Multi-label handles missing values
-
-**Use Cases:**
-- Drug safety prediction
-- Virtual screening
-- ADMET property prediction
-
-### Drug Discovery Regression
-
-| Dataset | Size | Property | Units | Description |
-|---------|------|----------|-------|-------------|
-| **ESOL** | 1,128 | Solubility | log(mol/L) | Water solubility |
-| **FreeSolv** | 642 | Hydration | kcal/mol | Hydration free energy |
-| **Lipophilicity** | 4,200 | LogD | - | Octanol/water distribution |
-| **SAMPL** | 643 | Solvation | kcal/mol | Solvation free energies |
-
-**Metrics:** MAE, RMSE, R²
-**Use Cases:** ADME optimization, lead optimization
-
-### Quantum Chemistry
-
-| Dataset | Size | Properties | Description |
-|---------|------|------------|-------------|
-| **QM7** | 7,165 | 1 | Atomization energy |
-| **QM8** | 21,786 | 12 | Electronic spectra, excited states |
-| **QM9** | 133,885 | 12 | Geometric, energetic, electronic, thermodynamic |
-| **PCQM4M** | 3.8M | 1 | Large-scale HOMO-LUMO gap |
-
-**Properties (QM9):**
-- Dipole moment
-- Isotropic polarizability
-- HOMO/LUMO energies
-- Internal energy, enthalpy, free energy
-- Heat capacity
-- Electronic spatial extent
-
-**Use Cases:**
-- Quantum property prediction
-- Method development benchmarking
-- Pre-training molecular models
-
-### Large Molecule Databases
-
-| Dataset | Size | Description | Use Case |
-|---------|------|-------------|----------|
-| **ZINC250k** | 250,000 | Drug-like molecules | Generative model training |
-| **ZINC2M** | 2,000,000 | Drug-like molecules | Large-scale pre-training |
-| **ChEMBL** | Millions | Bioactive molecules | Property prediction, generation |
-
-## Protein Datasets
-
-### Function Prediction
-
-| Dataset | Size | Task | Classes | Description |
-|---------|------|------|---------|-------------|
-| **EnzymeCommission** | 17,562 | Multi-class | 7 levels | EC number classification |
-| **GeneOntology** | 46,796 | Multi-label | 489 | GO term prediction (BP/MF/CC) |
-| **BetaLactamase** | 5,864 | Regression | - | Enzyme activity levels |
-| **Fluorescence** | 54,025 | Regression | - | GFP fluorescence intensity |
-| **Stability** | 53,614 | Regression | - | Thermostability (ΔΔG) |
-
-**Features:**
-- Sequence and/or structure input
-- Evolutionary information available
-- Multiple train/test splits
-
-**Use Cases:**
-- Protein engineering
-- Function annotation
-- Enzyme design
-
-### Localization and Solubility
-
-| Dataset | Size | Task | Classes | Description |
-|---------|------|------|---------|-------------|
-| **Solubility** | 62,478 | Binary | 2 | Protein solubility |
-| **BinaryLocalization** | 22,168 | Binary | 2 | Membrane vs soluble |
-| **SubcellularLocalization** | 8,943 | Multi-class | 10 | Subcellular compartment |
-
-**Use Cases:**
-- Protein expression optimization
-- Target identification
-- Cell biology
-
-### Structure Prediction
-
-| Dataset | Size | Task | Description |
-|---------|------|------|-------------|
-| **Fold** | 16,712 | Multi-class (1,195) | Structural fold recognition |
-| **SecondaryStructure** | 8,678 | Sequence labeling | 3-state or 8-state prediction |
-| **ProteinNet** | Varied | Contact prediction | Residue-residue contacts |
-
-**Use Cases:**
-- Structure prediction pipelines
-- Fold recognition
-- Contact map generation
-
-### Protein Interactions
-
-| Dataset | Size | Positives | Negatives | Description |
-|---------|------|-----------|-----------|-------------|
-| **HumanPPI** | 1,412 proteins | 6,584 | - | Human protein interactions |
-| **YeastPPI** | 2,018 proteins | 6,451 | - | Yeast protein interactions |
-| **PPIAffinity** | 2,156 pairs | - | - | Binding affinity values |
-
-**Use Cases:**
-- PPI prediction
-- Network biology
-- Drug target identification
-
-### Protein-Ligand Binding
-
-| Dataset | Size | Type | Description |
-|---------|------|------|-------------|
-| **BindingDB** | ~1.5M | Affinity | Comprehensive binding data |
-| **PDBBind** | 20,000+ | 3D complexes | Structure-based binding |
-| - Refined Set | 5,316 | High quality | Curated crystal structures |
-| - Core Set | 285 | Benchmark | Diverse test set |
-
-**Use Cases:**
-- Binding affinity prediction
-- Structure-based drug design
-- Scoring function development
-
-### Large Protein Databases
-
-| Dataset | Size | Description |
-|---------|------|-------------|
-| **AlphaFoldDB** | 200M+ | Predicted structures for most known proteins |
-| **UniProt** | Integration | Sequence and annotation data |
-
-## Knowledge Graph Datasets
-
-### General Knowledge
-
-| Dataset | Entities | Relations | Triples | Domain |
-|---------|----------|-----------|---------|--------|
-| **FB15k** | 14,951 | 1,345 | 592,213 | Freebase (general knowledge) |
-| **FB15k-237** | 14,541 | 237 | 310,116 | Filtered Freebase |
-| **WN18** | 40,943 | 18 | 151,442 | WordNet (lexical) |
-| **WN18RR** | 40,943 | 11 | 93,003 | Filtered WordNet |
-
-**Relation Types (FB15k-237):**
-- `/people/person/nationality`
-- `/film/film/genre`
-- `/location/location/contains`
-- `/business/company/founders`
-- Many more...
-
-**Use Cases:**
-- Link prediction
-- Relation extraction
-- Knowledge base completion
-
-### Biomedical Knowledge
-
-| Dataset | Entities | Relations | Triples | Description |
-|---------|----------|-----------|---------|-------------|
-| **Hetionet** | 45,158 | 24 | 2,250,197 | Integrates 29 biomedical databases |
-
-**Entity Types in Hetionet:**
-- Genes (20,945)
-- Compounds (1,552)
-- Diseases (137)
-- Anatomy (400)
-- Pathways (1,822)
-- Pharmacologic classes
-- Side effects
-- Symptoms
-- Molecular functions
-- Biological processes
-- Cellular components
-
-**Relation Types:**
-- Compound-binds-Gene
-- Gene-associates-Disease
-- Disease-presents-Symptom
-- Compound-treats-Disease
-- Compound-causes-Side effect
-- Gene-participates-Pathway
-- And 18 more...
-
-**Use Cases:**
-- Drug repurposing
-- Disease mechanism discovery
-- Target identification
-- Multi-hop reasoning in biomedicine
-
-## Citation Network Datasets
-
-| Dataset | Nodes | Edges | Classes | Description |
-|---------|-------|-------|---------|-------------|
-| **Cora** | 2,708 | 5,429 | 7 | Machine learning papers |
-| **CiteSeer** | 3,327 | 4,732 | 6 | Computer science papers |
-| **PubMed** | 19,717 | 44,338 | 3 | Biomedical papers |
-
-**Use Cases:**
-- Node classification
-- GNN baseline comparisons
-- Method development
-
-## Retrosynthesis Datasets
-
-| Dataset | Size | Description |
-|---------|------|-------------|
-| **USPTO-50k** | 50,017 | Curated patent reactions, single-step |
-
-**Features:**
-- Product → Reactants mapping
-- Atom mapping for reaction centers
-- Canonicalized SMILES
-- Balanced across reaction types
-
-**Splits:**
-- Train: ~40,000
-- Validation: ~5,000
-- Test: ~5,000
-
-**Use Cases:**
-- Retrosynthesis prediction
-- Reaction type classification
-- Synthetic route planning
-
-## Dataset Usage Patterns
-
-### Loading Datasets
-
-```python
-from torchdrug import datasets
-
-# Basic loading
-dataset = datasets.BBBP("~/molecule-datasets/")
-
-# With transforms
-from torchdrug import transforms
-transform = transforms.VirtualNode()
-dataset = datasets.BBBP("~/molecule-datasets/", transform=transform)
-
-# Protein dataset
-dataset = datasets.EnzymeCommission("~/protein-datasets/")
-
-# Knowledge graph
-dataset = datasets.FB15k237("~/kg-datasets/")
-```
-
-### Data Splitting
-
-```python
-# Random split
-train, valid, test = dataset.split([0.8, 0.1, 0.1])
-
-# Scaffold split (for molecules)
-from torchdrug import utils
-train, valid, test = dataset.split(
-    utils.scaffold_split(dataset, [0.8, 0.1, 0.1])
-)
-
-# Predefined splits (some datasets)
-train, valid, test = dataset.split()
-```
-
-### Feature Extraction
-
-**Node Features (Molecules):**
-- Atom type (one-hot or embedding)
-- Formal charge
-- Hybridization
-- Aromaticity
-- Number of hydrogens
-- Chirality
-
-**Edge Features (Molecules):**
-- Bond type (single, double, triple, aromatic)
-- Stereochemistry
-- Conjugation
-- Ring membership
-
-**Node Features (Proteins):**
-- Amino acid type (one-hot)
-- Physicochemical properties
-- Position in sequence
-- Secondary structure
-- Solvent accessibility
-
-**Edge Features (Proteins):**
-- Edge type (sequential, spatial, contact)
-- Distance
-- Angles and dihedrals
-
-## Choosing Datasets
-
-### By Task
-
-**Molecular Property Prediction:**
-- Start with BBBP or HIV (medium size, clear task)
-- Use QM9 for quantum properties
-- ESOL/FreeSolv for regression
-
-**Protein Function:**
-- EnzymeCommission (well-defined classes)
-- GeneOntology (comprehensive annotations)
-
-**Drug Safety:**
-- Tox21 (standard benchmark)
-- ClinTox (clinical relevance)
-
-**Structure-Based:**
-- PDBBind (protein-ligand)
-- ProteinNet (structure prediction)
-
-**Knowledge Graph:**
-- FB15k-237 (standard benchmark)
-- Hetionet (biomedical applications)
-
-**Generation:**
-- ZINC250k (training)
-- QM9 (with properties)
-
-**Retrosynthesis:**
-- USPTO-50k (only choice)
-
-### By Size and Resources
-
-**Small (<5k, for testing):**
-- BACE, FreeSolv, ClinTox
-- Core set of PDBBind
-
-**Medium (5k-100k):**
-- BBBP, HIV, ESOL, Tox21
-- EnzymeCommission, Fold
-- FB15k-237, WN18RR
-
-**Large (>100k):**
-- QM9, MUV, PCQM4M
-- GeneOntology, AlphaFoldDB
-- ZINC2M, BindingDB
-
-### By Domain
-
-**Drug Discovery:** BBBP, HIV, Tox21, ESOL, ZINC
-**Quantum Chemistry:** QM7, QM8, QM9, PCQM4M
-**Protein Engineering:** Fluorescence, Stability, Solubility
-**Structural Biology:** Fold, PDBBind, ProteinNet, AlphaFoldDB
-**Biomedical:** Hetionet, GeneOntology, EnzymeCommission
-**Retrosynthesis:** USPTO-50k
-
-## Best Practices
-
-1. **Start Small**: Test on small datasets before scaling
-2. **Scaffold Split**: Use for realistic drug discovery evaluation
-3. **Balanced Metrics**: Use AUROC + AUPRC for imbalanced data
-4. **Multiple Runs**: Report mean ± std over multiple random seeds
-5. **Data Leakage**: Be careful with pre-trained models
-6. **Domain Knowledge**: Understand what you're predicting
-7. **Validation**: Always use held-out test set
-8. **Preprocessing**: Standardize features, handle missing values

package/bin/skills/torchdrug/references/knowledge_graphs.md

@@ -1,320 +0,0 @@
-# Knowledge Graph Reasoning
-
-## Overview
-
-Knowledge graphs represent structured information as entities and relations in a graph format. TorchDrug provides comprehensive support for knowledge graph completion (link prediction) using embedding-based models and neural reasoning approaches.
-
-## Available Datasets
-
-### General Knowledge Graphs
-
-**FB15k (Freebase subset):**
-- 14,951 entities
-- 1,345 relation types
-- 592,213 triples
-- General world knowledge from Freebase
-
-**FB15k-237:**
-- 14,541 entities
-- 237 relation types
-- 310,116 triples
-- Filtered version removing inverse relations
-- More challenging benchmark
-
-**WN18 (WordNet):**
-- 40,943 entities (word senses)
-- 18 relation types (lexical relations)
-- 151,442 triples
-- Linguistic knowledge graph
-
-**WN18RR:**
-- 40,943 entities
-- 11 relation types
-- 93,003 triples
-- Filtered WordNet removing easy inverse patterns
-
-### Biomedical Knowledge Graphs
-
-**Hetionet:**
-- 45,158 entities (genes, compounds, diseases, pathways, etc.)
-- 24 relation types (treats, causes, binds, etc.)
-- 2,250,197 edges
-- Integrates 29 public biomedical databases
-- Designed for drug repurposing and disease understanding
-
-## Task: KnowledgeGraphCompletion
-
-The primary task for knowledge graphs is link prediction - given a head entity and relation, predict the tail entity (or vice versa).
-
-### Task Modes
-
-**Head Prediction:**
-- Given (?, relation, tail), predict head entity
-- "What can cause Disease X?"
-
-**Tail Prediction:**
-- Given (head, relation, ?), predict tail entity
-- "What diseases does Gene X cause?"
-
-**Both:**
-- Predict both head and tail
-- Standard evaluation protocol
-
-### Evaluation Metrics
-
-**Ranking Metrics:**
-- **Mean Rank (MR)**: Average rank of correct entity
-- **Mean Reciprocal Rank (MRR)**: Average of 1/rank
-- **Hits@K**: Percentage of correct entities in top K predictions
-  - Typically reported for K=1, 3, 10
-
-**Filtered vs Raw:**
-- **Filtered**: Remove other known true triples from ranking
-- **Raw**: Rank among all possible entities
-- Filtered is standard for evaluation
-
-## Embedding Models
-
-### Translational Models
-
-**TransE (Translation Embedding):**
-- Represents relations as translations in embedding space
-- h + r ≈ t (head + relation ≈ tail)
-- Simple and effective baseline
-- Works well for 1-to-1 relations
-- Struggles with N-to-N relations
-
-**RotatE (Rotation Embedding):**
-- Relations as rotations in complex space
-- Better handles symmetric and inverse relations
-- State-of-the-art on many benchmarks
-- Can model composition patterns
-
-### Semantic Matching Models
-
-**DistMult:**
-- Bilinear scoring function
-- Handles symmetric relations naturally
-- Cannot model asymmetric relations
-- Fast and memory efficient
-
-**ComplEx:**
-- Complex-valued embeddings
-- Models asymmetric and inverse relations
-- Better than DistMult for most graphs
-- Balances expressiveness and efficiency
-
-**SimplE:**
-- Extends DistMult with inverse relations
-- Fully expressive (can represent any relation pattern)
-- Two embeddings per entity (canonical and inverse)
-
-### Neural Logic Models
-
-**NeuralLP (Neural Logic Programming):**
-- Learns logical rules through differentiable operations
-- Interprets predictions via learned rules
-- Good for sparse knowledge graphs
-- Computationally more expensive
-
-**KBGAT (Knowledge Base Graph Attention):**
-- Graph attention networks for KG completion
-- Learns entity representations from neighborhood
-- Handles unseen entities through inductive learning
-- Better for incomplete graphs
-
-## Training Workflow
-
-### Basic Pipeline
-
-```python
-from torchdrug import datasets, models, tasks, core
-
-# Load dataset
-dataset = datasets.FB15k237("~/kg-datasets/")
-
-# Define model
-model = models.RotatE(
-    num_entity=dataset.num_entity,
-    num_relation=dataset.num_relation,
-    embedding_dim=2000,
-    max_score=9
-)
-
-# Define task
-task = tasks.KnowledgeGraphCompletion(
-    model,
-    num_negative=128,
-    adversarial_temperature=2,
-    criterion="bce"
-)
-
-# Train with PyTorch Lightning or custom loop
-```
-
-### Negative Sampling
-
-**Strategies:**
-- **Uniform**: Sample entities uniformly at random
-- **Self-Adversarial**: Weight samples by current model's scores
-- **Type-Constrained**: Sample only valid entity types for relation
-
-**Parameters:**
-- `num_negative`: Number of negative samples per positive triple
-- `adversarial_temperature`: Temperature for self-adversarial weighting
-- Higher temperature = more focus on hard negatives
-
-### Loss Functions
-
-**Binary Cross-Entropy (BCE):**
-- Treats each triple independently
-- Balanced classification between positive and negative
-
-**Margin Loss:**
-- Ensures positive scores higher than negative by margin
-- `max(0, margin + score_neg - score_pos)`
-
-**Logistic Loss:**
-- Smooth version of margin loss
-- Better gradient properties
-
-## Model Selection Guide
-
-### By Relation Patterns
-
-**1-to-1 Relations:**
-- TransE works well
-- Any model will likely succeed
-
-**1-to-N Relations:**
-- DistMult, ComplEx, SimplE
-- Avoid TransE
-
-**N-to-1 Relations:**
-- DistMult, ComplEx, SimplE
-- Avoid TransE
-
-**N-to-N Relations:**
-- ComplEx, SimplE, RotatE
-- Most challenging pattern
-
-**Symmetric Relations:**
-- DistMult, ComplEx
-- RotatE with proper initialization
-
-**Antisymmetric Relations:**
-- ComplEx, SimplE, RotatE
-- Avoid DistMult
-
-**Inverse Relations:**
-- ComplEx, SimplE, RotatE
-- Important for bidirectional reasoning
-
-**Composition:**
-- RotatE (best)
-- TransE (reasonable)
-- Captures multi-hop paths
-
-### By Dataset Characteristics
-
-**Small Graphs (< 50k entities):**
-- ComplEx or SimplE
-- Lower embedding dimensions (200-500)
-
-**Large Graphs (> 100k entities):**
-- DistMult for efficiency
-- RotatE for accuracy
-- Higher dimensions (500-2000)
-
-**Sparse Graphs:**
-- NeuralLP (learns rules from limited data)
-- Pre-train embeddings on larger graphs
-
-**Dense, Complete Graphs:**
-- Any embedding model works well
-- Choose based on relation patterns
-
-**Biomedical/Domain Graphs:**
-- Consider type constraints in sampling
-- Use domain-specific negative sampling
-- Hetionet benefits from relation-specific models
-
-## Advanced Techniques
-
-### Multi-Hop Reasoning
-
-Chain multiple relations to answer complex queries:
-- "What drugs treat diseases caused by gene X?"
-- Requires path-based or rule-based reasoning
-- NeuralLP naturally supports this
-
-### Temporal Knowledge Graphs
-
-Extend to time-varying facts:
-- Add temporal information to triples
-- Predict future facts
-- Requires temporal encoding in models
-
-### Few-Shot Learning
-
-Handle relations with few examples:
-- Meta-learning approaches
-- Transfer from related relations
-- Important for emerging knowledge
-
-### Inductive Learning
-
-Generalize to unseen entities:
-- KBGAT and other GNN-based methods
-- Use entity features/descriptions
-- Critical for evolving knowledge graphs
-
-## Biomedical Applications
-
-### Drug Repurposing
-
-Predict "drug treats disease" links in Hetionet:
-1. Train on known drug-disease associations
-2. Predict new treatment candidates
-3. Filter by mechanism (gene, pathway involvement)
-4. Validate predictions experimentally
-
-### Disease Gene Discovery
-
-Identify genes associated with diseases:
-1. Model gene-disease-pathway networks
-2. Predict missing gene-disease links
-3. Incorporate protein interactions, expression data
-4. Prioritize candidates for validation
-
-### Protein Function Prediction
-
-Link proteins to biological processes:
-1. Integrate protein interactions, GO terms
-2. Predict missing GO annotations
-3. Transfer function from similar proteins
-
-## Common Issues and Solutions
-
-**Issue: Poor performance on specific relation types**
-- Solution: Analyze relation patterns, choose appropriate model, or use relation-specific models
-
-**Issue: Overfitting on small graphs**
-- Solution: Reduce embedding dimension, increase regularization, or use simpler models
-
-**Issue: Slow training on large graphs**
-- Solution: Reduce negative samples, use DistMult for efficiency, or implement mini-batch training
-
-**Issue: Cannot handle new entities**
-- Solution: Use inductive models (KBGAT), incorporate entity features, or pre-compute embeddings for new entities based on their neighbors
-
-## Best Practices
-
-1. Start with ComplEx or RotatE for most tasks
-2. Use self-adversarial negative sampling
-3. Tune embedding dimension (typically 500-2000)
-4. Apply regularization to prevent overfitting
-5. Use filtered evaluation metrics
-6. Analyze performance per relation type
-7. Consider relation-specific models for heterogeneous graphs
-8. Validate predictions with domain experts