Advanced Workflows¶
This guide covers advanced LearnM8 features for scaling to large compound libraries and maximizing active learning performance.
Pruning Large Compound Libraries¶
What is Pruning¶
Pruning removes low-value compounds from the unlabeled pool based on model predictions and uncertainties. This reduces computational costs and focuses active learning on promising regions.
Benefits:
- 10-50% computational savings
- Faster cycle times
- Focused search in chemical space
- Memory efficiency for large libraries
When to use:
- Compound pools > 100,000 compounds
- Limited computational budget
- Clear exploitation phase (later cycles)
- Low-scoring regions confirmed uninteresting
Score-Based Pruning¶
Remove compounds with poor predicted scores.
Python API Example:
from learnm8 import run_active_learning
results = run_active_learning(
compound_pool='large_library.csv',
oracle='oracle.py:score',
learner='gp',
target_col='affinity',
featurizer='morgan',
n_cycles=20,
pruning_strategy='score',
pruning_fraction=0.1,
score_direction='higher'
)
Removes bottom 10% of compounds by predicted score each cycle.
Parameters:
pruning_strategy:'score'for prediction-based pruningpruning_fraction: Fraction to remove (0.0-0.9), typically 0.1-0.3score_direction:'higher'or'lower'based on optimization goal
CLI Alternative:
learnm8 run large_library.csv oracle.py:score \
--target affinity \
--learner gp \
--featurizer morgan \
--n-cycles 20 \
--pruning-strategy score \
--pruning-fraction 0.1 \
--score-direction higher
Per-Cycle Pruning Strategy¶
Apply different pruning strategies per cycle using CycleConfig.
Example: Progressive Pruning
from learnm8.core.config import CycleConfig
cycles = [
# Cycle 0-1: No pruning (exploration)
CycleConfig('random', n_cycles=1, batch_fraction=0.02),
CycleConfig('ucb', n_cycles=5, batch_fraction=0.01),
# Cycle 6-10: Light pruning (10%)
CycleConfig(
'greedy',
n_cycles=5,
batch_fraction=0.01,
pruning_strategy='score',
pruning_params={'pruning_fraction': 0.1}
),
# Cycle 11-20: Aggressive pruning (30%)
CycleConfig(
'greedy',
n_cycles=10,
batch_fraction=0.01,
pruning_strategy='score',
pruning_params={'pruning_fraction': 0.3}
)
]
results = run_active_learning(
compound_pool='large_library.csv',
oracle='oracle.py:score',
learner='ensemble',
target_col='affinity',
featurizer='morgan',
cycles=cycles
)
Pruning Performance Example¶
Dataset: 500,000 compounds, 20 cycles, score-based pruning (20%)
| Cycle | Pool Size | Pruned | Predictions | Time Saved |
|---|---|---|---|---|
| 0 | 500,000 | 0 | 500,000 | - |
| 1 | 500,000 | 100,000 | 400,000 | 20% |
| 5 | 400,000 | 80,000 | 320,000 | 36% |
| 10 | 300,000 | 60,000 | 240,000 | 52% |
| 20 | 150,000 | 30,000 | 120,000 | 76% |
Cumulative computational savings: ~40%
Ensemble Learning¶
Why Ensembles¶
Ensemble learning combines multiple models to improve predictions and uncertainty quantification.
Advantages:
- Better uncertainty estimates through model disagreement
- Robustness to overfitting
- No hyperparameter tuning for uncertainty
- Captures different aspects of data
Uncertainty calculation:
Where:
prediction_variance: Average uncertainty from individual modelsmodel_disagreement: Variance across model predictions
Mixed Ensemble Example¶
Combines RandomForest, LinearRegression, and XGBoost for maximum diversity.
Python API Example:
from learnm8 import run_active_learning
from learnm8.learners.ensemble import MixedEnsemble
learner = MixedEnsemble(random_state=42)
results = run_active_learning(
compound_pool='compounds.csv',
oracle='oracle.py:score',
learner=learner,
target_col='affinity',
featurizer='morgan',
n_cycles=15,
batch_fraction=0.01
)
CLI Alternative:
learnm8 run compounds.csv oracle.py:score \
--target affinity \
--learner mixed_ensemble \
--featurizer morgan \
--n-cycles 15 \
--batch-fraction 0.01
Custom Ensemble¶
Create ensembles with specific model combinations.
from learnm8.learners.ensemble import EnsembleLearner
from learnm8.learners.sklearn import RandomForestLearner, GaussianProcessLearner
from learnm8.learners.sklearn import XGBoostLearner
learners = [
RandomForestLearner(n_estimators=100, random_state=42),
GaussianProcessLearner(random_state=42),
XGBoostLearner(learning_rate=0.1, random_state=42)
]
ensemble = EnsembleLearner(
learners=learners,
aggregation_method='mean',
uncertainty_method='std'
)
results = run_active_learning(
compound_pool='compounds.csv',
oracle='oracle.py:score',
learner=ensemble,
target_col='affinity',
featurizer='morgan',
n_cycles=15
)
Type-Specific Ensembles¶
LearnM8 provides pre-configured ensembles for common model types.
Available ensembles:
rf_ensemble: 3 RandomForest variantsxgb_ensemble: 3 XGBoost variantslr_ensemble: 3 LinearRegression variantsdt_ensemble: 3 DecisionTree variantsfastprop_ensemble: 3 FastProp neural networkschemprop_ensemble: 3 Chemprop graph neural networks
Python API Example:
from learnm8 import run_active_learning
results = run_active_learning(
compound_pool='compounds.csv',
oracle='oracle.py:score',
learner='rf_ensemble',
target_col='affinity',
featurizer='morgan',
n_cycles=10
)
CLI Alternative:
learnm8 run compounds.csv oracle.py:score \
--target affinity \
--learner rf_ensemble \
--featurizer morgan \
--n-cycles 10
Ensemble Performance Considerations¶
Computational cost:
- 3x training time (3 models)
- 3x prediction time
- 3x memory usage
- No parallelization (sequential training)
When worth the cost:
- Uncertainty-based acquisition (UCB, EI, Thompson)
- Small to medium datasets (< 50,000 compounds)
- High-value measurements (expensive oracles)
- Research and benchmarking
When to use single models:
- Very large datasets (> 100,000 compounds)
- Greedy acquisition (no uncertainty needed)
- Computational budget constraints
- Production with time limits
Chemprop Fine-Tuning¶
What is Fine-Tuning¶
Fine-tuning for active learning reuses trained model weights from previous cycles as initialization for subsequent training, instead of training from scratch each cycle.
Benefits:
- Faster convergence (fewer epochs needed)
- Better uncertainty calibration
- Improved performance with small batches
- Preserved learned representations
Computational cost:
- 20-40% faster training per cycle
- Additional checkpoint storage (minimal)
- No prediction cost increase
Enabling Fine-Tuning¶
Python API Example:
from learnm8 import run_active_learning
from learnm8.learners.torch import ChempropLearner
from pathlib import Path
learner = ChempropLearner(
enable_fine_tuning=True,
checkpoint_dir=Path('./checkpoints'),
max_epochs=50,
learning_rate=1e-4
)
results = run_active_learning(
compound_pool='compounds.csv',
oracle='oracle.py:score',
learner=learner,
target_col='affinity',
n_cycles=20,
batch_fraction=0.005
)
Chemprop fine-tuning is only available via the Python API (no CLI equivalent).
Fine-Tuning Parameters¶
Learner initialization:
learner = ChempropLearner(
enable_fine_tuning=True,
checkpoint_dir=Path('./checkpoints'),
max_epochs=50,
early_stopping=True,
early_stopping_patience=3
)
Parameters:
enable_fine_tuning: Enable checkpoint-based fine-tuning (default: False)checkpoint_dir: Directory for checkpoint storage (required if fine-tuning)max_epochs: Maximum epochs per training cycleearly_stopping: Stop when validation loss plateausearly_stopping_patience: Epochs to wait before stopping
Example Workflow¶
Complete active learning campaign with fine-tuning:
from learnm8 import run_active_learning
from learnm8.learners.ensemble import ChempropEnsemble
from pathlib import Path
learner = ChempropEnsemble(
n_models=3,
enable_fine_tuning=True,
checkpoint_dir=Path('./checkpoints/chemprop_ensemble'),
max_epochs=50,
batch_size=32,
learning_rate=1e-4,
early_stopping=True
)
results = run_active_learning(
compound_pool='screening_library.csv',
oracle='docking_oracle.py:dock_compounds',
learner=learner,
target_col='docking_score',
score_direction='lower',
cycles=[
('random', 0.02),
('ucb', 0.01),
('ucb', 0.01),
('ucb', 0.01),
('greedy', 0.005),
('greedy', 0.005),
('greedy', 0.005),
CycleConfig('simulated_annealing', n_cycles=1, batch_fraction=0.01),
],
output_format='csv',
output_dir='results/chemprop_fine_tuned'
)
Checkpoint management:
checkpoints/chemprop_ensemble/
├── model_0_cycle_1.ckpt
├── model_0_cycle_2.ckpt
├── model_1_cycle_1.ckpt
├── model_1_cycle_2.ckpt
├── model_2_cycle_1.ckpt
└── model_2_cycle_2.ckpt
Fine-Tuning vs From-Scratch Comparison¶
Small batch scenario (0.5% per cycle):
| Cycle | From Scratch Epochs | Fine-Tuning Epochs | Speedup |
|---|---|---|---|
| 1 | 50 | 50 | 1.0x |
| 2 | 50 | 20 | 2.5x |
| 5 | 50 | 15 | 3.3x |
| 10 | 50 | 12 | 4.2x |
| 20 | 50 | 10 | 5.0x |
Average training time reduction: 60%
When Fine-Tuning Helps Most¶
Ideal scenarios:
- Small batch sizes (< 1% per cycle)
- Many cycles (> 10 cycles)
- Chemprop or deep learning models
- Limited computational budget
- Incremental learning tasks
Less beneficial:
- Large batch sizes (> 5% per cycle)
- Few cycles (< 5 cycles)
- Traditional ML models (RF, XGB)
- Abundant GPU resources
Configuration Files for Reproducibility¶
Creating YAML Configuration¶
Store complete experiment parameters in version-controlled configuration files.
Example: experiment_config.yaml
compound_pool: screening_library.csv
oracle: docking_oracle.py:dock_compounds
learner: chemprop_ensemble
target_col: docking_score
featurizer: morgan
score_direction: lower
random_state: 42
output_dir: results/docking_campaign_001
cycles:
- strategy: random
batch_fraction: 0.02
n_cycles: 1
- strategy: ucb
batch_fraction: 0.01
n_cycles: 5
acquisition_params:
beta: 2.0
- strategy: greedy
batch_fraction: 0.005
n_cycles: 10
pruning_strategy: score
pruning_fraction: 0.15
- strategy: simulated_annealing
batch_fraction: 0.01
n_cycles: 4
output_format: csv
cache_dir: .cache/docking_features
Loading Configuration¶
Python API:
import yaml
from learnm8 import run_active_learning
with open('experiment_config.yaml') as f:
config = yaml.safe_load(f)
results = run_active_learning(**config)
CLI:
Override specific parameters:
learnm8 run --config experiment_config.yaml \
--random-state 123 \
--output results/docking_campaign_002
Version Control for Experiments¶
Directory structure:
project/
├── configs/
│ ├── baseline_rf.yaml
│ ├── ensemble_ucb.yaml
│ ├── chemprop_finetuned.yaml
│ └── production_campaign.yaml
├── oracles/
│ ├── docking_oracle.py
│ ├── qsar_oracle.py
│ └── experimental_oracle.py
├── data/
│ ├── screening_library.csv
│ └── validation_set.csv
├── results/
│ ├── exp_001/
│ ├── exp_002/
│ └── exp_003/
└── checkpoints/
├── exp_001/
└── exp_002/
Git workflow:
# Version control configurations
git add configs/production_campaign.yaml
git commit -m "Add production campaign configuration"
# Run experiment
learnm8 run --config configs/production_campaign.yaml
# Version control results metadata
git add results/exp_001/metadata.json
git commit -m "Record experiment 001 results"
Configuration Templates¶
Quick exploration:
# configs/quick_explore.yaml
compound_pool: compounds.csv
oracle: oracle.py:score
learner: rf
target_col: activity
featurizer: morgan
n_cycles: 5
batch_fraction: 0.02
random_state: 42
Intensive campaign:
# configs/intensive_campaign.yaml
compound_pool: large_library.csv
oracle: oracle.py:score
learner: chemprop_ensemble
target_col: affinity
featurizer: morgan
score_direction: higher
random_state: 42
cycles:
- strategy: random
batch_fraction: 0.01
n_cycles: 1
- strategy: ucb
batch_fraction: 0.005
n_cycles: 10
acquisition_params:
beta: 2.0
- strategy: greedy
batch_fraction: 0.005
n_cycles: 15
pruning_strategy: score
pruning_fraction: 0.2
output_format: csv
cache_dir: .cache/intensive
Best Practices¶
Configuration management:
- Use descriptive config names (
chemprop_ucb_beta2.yaml) - Include
random_statefor reproducibility - Document parameter choices in comments
- Version control all configs
- Store oracle code with configs
Experiment tracking:
- Unique output directories per experiment
- Record git commit hash in results
- Save config copy to output directory
- Document hypothesis and conclusions
- Archive checkpoints for successful runs
Parameter search: