CLI Reference¶
LearnM8 provides a command-line interface for running active learning experiments and validating compounds. The CLI has two subcommands: run and validate.
Getting Help¶
Access help information at any level:
Command Overview¶
LearnM8 CLI has two subcommands:
| Subcommand | Purpose | Common Usage |
|---|---|---|
run |
Execute active learning experiment | Main workflow for screening |
validate |
Validate compound pool | Pre-flight check before experiments |
learnm8 run¶
Run an active learning experiment with specified configuration.
Basic Syntax¶
Positional Arguments¶
| Argument | Required | Description |
|---|---|---|
COMPOUND_POOL |
Yes | CSV file with compound library (must have ID and SMILES columns) |
ORACLE |
No | Oracle specification (auto-detected if omitted) |
Oracle Formats:
- CSV file:
oracle.csv(benchmark mode with ground truth) - Python module:
module.py:function(production mode with custom scoring) - Auto-detect: Omit to use
COMPOUND_POOLas oracle (benchmark mode)
Required Parameters¶
| Parameter | Type | Description |
|---|---|---|
--target COLUMN |
string | Target property column name in CSV |
--featurizer TYPE |
choice | Molecular featurizer. Required unless using chemprop or fastprop (see Available Featurizers for the full list of 39 options) |
Featurizer Choices: See Available Featurizers for the full list of 39 options. Common choices: morgan, maccs, ecfp6, descriptors, morgan_feat.
Core Configuration¶
| Parameter | Type | Default | Description |
|---|---|---|---|
--learner MODEL |
choice | rf |
Machine learning model (see learner choices) |
--score-direction DIR |
choice | higher |
Optimization direction: higher or lower |
Learner Choices (availability depends on installed dependencies):
- Scikit-learn:
rf,gp,xgb,dt,lr - PyTorch:
mlp,mc_dropout,fastprop - Graph Neural Networks:
chemprop,chemprop_ensemble - Ensembles:
ensemble,mixed_ensemble,rf_ensemble,xgb_ensemble, etc.
Use from learnm8.api import list_available_learners; list_available_learners() (Python) to see all available learners in your environment.
Cycle Control (Mutually Exclusive)¶
Only one of these options can be used:
Option 1: Custom Cycle Specification (Recommended)¶
| Parameter | Type | Description |
|---|---|---|
--cycles SPEC |
string | Explicit cycle specification with strategy and batch fractions |
Cycle Specification Format:
Examples:
--cycles "random:0.02 greedy:0.01*5"
--cycles "random:0.01 ucb:0.005*8 simulated_annealing:0.01*2"
--cycles "random:0.02 greedy:0.01 ucb:0.01 greedy:0.01"
Strategy Multiplier: Use *n to repeat a strategy n times:
greedy:0.01*5= 5 cycles of greedy with 0.01 batch fraction- Equivalent to:
greedy:0.01 greedy:0.01 greedy:0.01 greedy:0.01 greedy:0.01
Option 2: Configuration File¶
| Parameter | Type | Description |
|---|---|---|
--config PATH |
file | YAML or JSON configuration file |
Example:
Configuration files can specify all parameters including cycles. See Configuration Files for details.
Option 3: Simple Mode (Default)¶
If no cycle control option is specified, simple mode is used with these parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
--n-cycles N |
integer | 10 | Number of active learning cycles |
--batch-fraction F |
float | 0.01 | Fraction of pool to select per cycle (1%) |
--strategy NAME |
string | greedy |
Main acquisition strategy |
--initial-strategy NAME |
string | random |
First cycle strategy |
Example:
learnm8 run compounds.csv --target Activity --featurizer morgan --learner gp \
--n-cycles 15 --batch-fraction 0.005 --strategy greedy --initial-strategy random
Pruning Options¶
| Parameter | Type | Default | Description |
|---|---|---|---|
--pruning-fraction F |
float | None | Fraction of pool to prune each cycle (0.0-0.9) |
--pruning-strategy NAME |
string | score |
Pruning strategy |
Pruning Strategy:
score- Remove lowest-scoring compounds based on model predictions
Pruning Parameters:
pruning_fraction(float, 0.0-0.9): Fraction of pool to prune each cyclepruning_threshold(float, optional): Absolute score threshold for pruning (alternative to fraction)
Example:
learnm8 run large_library.csv --target Activity --featurizer morgan --learner rf \
--pruning-fraction 0.3 --pruning-strategy score
Acquisition Parameters¶
| Parameter | Type | Description |
|---|---|---|
--acquisition-params JSON |
string | JSON string of acquisition function parameters |
Example (UCB with custom beta):
learnm8 run compounds.csv --target Activity --featurizer morgan --learner gp \
--cycles "ucb:0.01*10" \
--acquisition-params '{"beta": 2.5}'
Example (TopK with fraction):
learnm8 run compounds.csv --target Activity --featurizer morgan --learner rf \
--cycles "topk:0.01*8" \
--acquisition-params '{"k_fraction": 0.1}'
Output Options¶
| Parameter | Type | Default | Description |
|---|---|---|---|
-o PATH / --output PATH |
directory | Auto-generated | Output directory for results |
--cache-dir PATH |
directory | {output}/.cache |
HDF5 feature cache directory |
--quiet |
flag | False | Suppress progress output |
Output Directory Structure:
output_dir/
├── compounds_final.csv # Final compound status
├── cycle_metrics.csv # Per-cycle metrics
├── selection_history.csv # Compound selection history
├── validation_report.csv # SMILES validation results
├── experiment_config.json # Complete configuration
└── .cache/ # Feature cache (if cache-dir not specified)
└── features_morgan_packed_uint8.h5 # Cached molecular features
Cache Directory: The feature cache persists across runs, providing 100x speedup when reusing the same compounds and featurizer. Share cache across experiments by specifying a common --cache-dir.
Advanced Options¶
| Parameter | Type | Default | Description |
|---|---|---|---|
--random-state SEED |
integer | 42 | Random seed for reproducibility |
--n-jobs N |
integer | -1 | CPU parallelism. -1 = all cores |
--device DEVICE |
string | auto |
Compute device: auto, cpu, cuda, cuda:N, mps |
--memory-safety-factor F |
float | 0.7 | Fraction of available memory to use for prediction batching |
--output-format FORMAT |
choice | auto |
Output format: auto, csv, parquet. Auto selects parquet for >1M rows |
--allow-large-features |
flag | False | Bypass the large-feature guard that blocks descriptor featurizers on pools >1M compounds |
--force-uncertainty |
flag | False | Force uncertainty computation every cycle, even for greedy/random/topk. Useful for diagnostics |
Mode auto-detection (not overridable via CLI):
- CSV oracle → benchmark mode (comprehensive discovery and ranking metrics)
- Python oracle → run mode (basic metrics only)
learnm8 validate¶
Validate compound pool using datamol SMILES validation before running experiments.
Syntax¶
Parameters¶
| Parameter | Required | Type | Description |
|---|---|---|---|
COMPOUND_POOL |
Yes | file | CSV file with compounds (must have ID and SMILES columns) |
-o PATH / --output PATH |
No | directory | Output directory for validation report |
Validation Process¶
The validation command:
- Reads compound CSV file
- Validates each SMILES string using datamol
- Identifies valid and invalid compounds
- Reports success rate and sample errors
- Optionally saves detailed validation report
Output¶
Console Output:
Validating: compounds.csv
Total compounds: 1000
✓ Validation complete
Valid compounds: 987 (98.7%)
Invalid compounds: 13
Sample errors:
comp_123: Invalid SMILES syntax
comp_456: Aromatic bonds on sp3 atoms
comp_789: Valence error for atom C
... and 10 more
Validation Report (if -o specified):
File: {output_dir}/validation_report.csv
| Column | Description |
|---|---|
| ID | Compound identifier |
| SMILES | Invalid SMILES string |
| error | Validation error message |
Examples¶
Basic Validation:
Save Validation Report:
Recommended Workflow:
learnm8 validate compounds.csv -o validation/
learnm8 run compounds.csv --target Activity --featurizer morgan --learner rf --n-cycles 10
Complete Examples¶
Example 1: Simple Benchmark Experiment¶
learnm8 run ESSENCE_benchmark_input/ADA.csv \
--target Activity \
--featurizer morgan \
--learner rf \
--n-cycles 15
What this does:
- Uses CSV file as both compound pool and oracle (benchmark mode)
- Random Forest model with Morgan fingerprints
- 15 cycles (1 random + 14 greedy by default)
- Auto-generated output directory
Example 2: Production Screening with Custom Oracle¶
learnm8 run compound_library.csv docking_module.py:calculate_binding \
--target binding_score \
--featurizer morgan \
--learner mc_dropout \
--cycles "random:0.01 ucb:0.005*10 greedy:0.01*5" \
--cache-dir .shared_cache \
-o screening_results/
What this does:
- Custom Python oracle for docking calculations
- MC Dropout for uncertainty quantification
- Multi-strategy cycles: random → UCB (10 cycles) → greedy (5 cycles)
- Shared feature cache for speed
- Explicit output directory
Example 3: Large Library with Pruning¶
learnm8 run large_library.csv oracle.py:score \
--target Activity \
--featurizer descriptors \
--learner ensemble \
--cycles "random:0.01 greedy:0.005*19" \
--pruning-fraction 0.3 \
--pruning-strategy score_based \
-o large_screen/
What this does:
- Ensemble learner for robustness
- 20 cycles (1 random + 19 greedy)
- Prune bottom 30% each cycle to reduce library size
- Mordred descriptors for rich chemical features
Example 4: Uncertainty-Based Exploration¶
learnm8 run compounds.csv --target Activity \
--featurizer morgan \
--learner gp \
--cycles "random:0.02 ucb:0.01*5 ei:0.01*3 greedy:0.01*2" \
--acquisition-params '{"beta": 3.0}' \
--random-state 12345
What this does:
- Gaussian Process for uncertainty estimation
- Mixed acquisition: random → UCB → Expected Improvement → greedy
- Custom UCB beta parameter (more exploration)
- Explicit random seed for reproducibility
Example 5: Graph Neural Network Screening¶
learnm8 run compounds.csv --target Activity \
--featurizer morgan \
--learner chemprop \
--n-cycles 10 \
-o chemprop_results/
What this does:
- Chemprop works directly with SMILES; the featurizer argument is required by the CLI but ignored by Chemprop unless running in hybrid mode (see
--learner chemprop --featurizer descriptors) - Graph neural network for state-of-the-art predictions
Example 6: Configuration File Workflow¶
experiment.yaml:
compound_pool: compounds.csv
oracle: oracle.csv
target_col: Activity
featurizer: morgan
learner: ensemble
cycles:
- strategy: random
batch_fraction: 0.02
n_cycles: 1
- strategy: greedy
batch_fraction: 0.01
n_cycles: 9
output_dir: results/
random_state: 42
Global Behavior¶
Reproducibility¶
All experiments use a random seed for reproducibility. Set explicitly with:
Default seed is 42. Change for independent runs.
Progress Output¶
By default, LearnM8 shows rich console output with progress bars and result tables. Suppress with:
Useful for automated workflows or logging to files.
Error Handling¶
LearnM8 provides clear error messages with suggestions:
- Missing files → Check path
- Invalid parameters → Show valid choices
- Dependency errors → Installation instructions
- SMILES validation errors → Use
validatesubcommand first
Exit Codes¶
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Error (file not found, invalid parameter, etc.) |
Best Practices¶
- Validate compounds first: Always run
learnm8 validatebefore experiments - Use explicit cycles: Prefer
--cyclesover simple mode for precise control - Share cache: Specify
--cache-dirfor experiments using same compounds - Name outputs: Use
-owith descriptive directory names - Set random state: Specify
--random-statefor reproducible experiments - Configuration files: Use YAML configs for complex experiments and reproducibility
Performance Tips¶
- Feature caching: First run computes features, subsequent runs are 100x faster with cache
- Shared cache: Reuse cache across experiments:
--cache-dir .shared_cache - Batch fractions: Smaller batches (0.005-0.01) balance cost vs performance
- Pruning: Use
--pruning-fractionfor libraries >100k compounds - Fast models: Use
rforxgbfor rapid iteration - GPU acceleration: Use
chempropormlpwith GPU for large datasets
Troubleshooting¶
Problem: "Compound pool file not found"
Solution: Check file path is correct and file existsProblem: "Invalid SMILES" errors during experiment
Solution: Fix invalid SMILES before running experimentProblem: "Learner 'chemprop' not available"
pip install chemprop
python -c "from learnm8.api import list_available_learners; print(list_available_learners())"
See Also¶
- API Reference - Python API documentation
- Configuration Files - YAML/JSON configuration format
- Running Experiments Tutorial - Step-by-step guide
- Building Custom Cycles - Cycle specification guide