Skip to content

Examples

Practical code examples for common LearnM8 workflows. For full parameter documentation, see the API Reference.

Basic Benchmark Experiment

The minimal workflow: run active learning against a CSV dataset to evaluate strategy performance.

from learnm8 import run_active_learning

results = run_active_learning(
    compound_pool='compounds.csv',
    oracle='oracle.csv',
    learner='rf',
    target_col='Activity',
    featurizer='morgan',
    n_cycles=10,
    batch_fraction=0.01,
    random_state=42,
)

for m in results['cycle_metrics']:
    print(f"Cycle {m['cycle']:2d} | strategy={m['strategy']:<8} | "
          f"labeled={m['n_labeled']:4d} | r2={m['r2_score']:.3f}")

Multi-Stage Acquisition with CycleConfig

Control exactly which strategy runs in each phase — random warm-start, uncertainty-guided exploration, then greedy exploitation.

from learnm8 import run_active_learning, CycleConfig

results = run_active_learning(
    compound_pool='compounds.csv',
    oracle='oracle.csv',
    learner='ensemble',
    target_col='Activity',
    featurizer='morgan',
    cycles=[
        CycleConfig('random',  n_cycles=1, batch_fraction=0.02),
        CycleConfig('ucb',     n_cycles=6, batch_fraction=0.005,
                    acquisition_params={'beta': 2.0}),
        CycleConfig('greedy',  n_cycles=3, batch_fraction=0.005,
                    acquisition_params={'score_direction': 'higher'}),
    ],
    random_state=42,
)

Production Screening with a Custom Oracle

Use a Python function as the oracle when measurements are expensive (docking, synthesis, etc.).

# scoring.py
def calculate_binding(compound_ids):
    import pandas as pd
    scores = [run_docking(cid) for cid in compound_ids]
    return pd.DataFrame({'ID': compound_ids, 'binding_score': scores})
from learnm8 import run_active_learning, CycleConfig

results = run_active_learning(
    compound_pool='virtual_library.csv',
    oracle='scoring.py:calculate_binding',
    learner='ensemble',
    target_col='binding_score',
    featurizer='morgan',
    cycles=[
        CycleConfig('random', n_cycles=1, batch_fraction=0.02),
        CycleConfig('ei',     n_cycles=9, batch_fraction=0.005),
    ],
    n_jobs=-1,
)

Gaussian Process with Uncertainty

GP provides calibrated uncertainty estimates — pair it with UCB, EI, PI, or Thompson sampling.

from learnm8 import run_active_learning, CycleConfig

results = run_active_learning(
    compound_pool='compounds.csv',
    oracle='oracle.csv',
    learner='gp',
    target_col='Activity',
    featurizer='morgan',
    cycles=[
        CycleConfig('random',   n_cycles=1, batch_fraction=0.02),
        CycleConfig('thompson', n_cycles=9, batch_fraction=0.005),
    ],
    random_state=42,
)

Skipping Uncertainty for Speed

When using a greedy strategy, uncertainty computation is skipped automatically. Use force_uncertainty=True to always compute it (e.g., for diagnostic logging).

from learnm8 import run_active_learning, CycleConfig

# Uncertainty skipped automatically — greedy doesn't need it
results = run_active_learning(
    compound_pool='compounds.csv',
    oracle='oracle.csv',
    learner='gp',
    target_col='Activity',
    featurizer='morgan',
    cycles=[
        CycleConfig('random', n_cycles=1, batch_fraction=0.02),
        CycleConfig('greedy', n_cycles=9, batch_fraction=0.005),
    ],
)

# Force uncertainty computation even for non-uncertainty strategies
results_diag = run_active_learning(
    compound_pool='compounds.csv',
    oracle='oracle.csv',
    learner='gp',
    target_col='Activity',
    featurizer='morgan',
    cycles=[
        CycleConfig('random', n_cycles=1, batch_fraction=0.02),
        CycleConfig('greedy', n_cycles=9, batch_fraction=0.005),
    ],
    force_uncertainty=True,
)

Large-Scale Screening (100M Compounds)

Optimise for scale with Parquet output, similarity metric disabled, and shared HDF5 cache.

from learnm8 import run_active_learning, CycleConfig
from pathlib import Path

results = run_active_learning(
    compound_pool='virtual_library_100M.csv',
    oracle='scoring.py:score',
    learner='rf',
    target_col='Activity',
    featurizer='morgan',
    cycles=[
        CycleConfig('random', n_cycles=1, batch_fraction=0.001),
        CycleConfig('greedy', n_cycles=9, batch_fraction=0.0005),
    ],
    cache_dir=Path('.shared_cache'),
    output_format='parquet',
    disable_molecular_similarity=True,
    large_features_ack=True,
    n_jobs=-1,
    random_state=42,
)

Simulated Annealing with Score-Band Neighbors

Use neighbor_strategy='score_band' for fast diversity-aware selection without computing pairwise distances.

from learnm8 import run_active_learning, CycleConfig

results = run_active_learning(
    compound_pool='compounds.csv',
    oracle='oracle.csv',
    learner='rf',
    target_col='Activity',
    featurizer='morgan',
    cycles=[
        CycleConfig('random',            n_cycles=1, batch_fraction=0.02),
        CycleConfig('simulated_annealing', n_cycles=9, batch_fraction=0.005,
                    acquisition_params={
                        'neighbor_strategy': 'score_band',
                        'band_width': 100,
                        'initial_temp': 2.0,
                        'cooling_schedule': 'linear',
                    }),
    ],
)

Chemprop Graph Neural Network

Chemprop operates directly on SMILES — no featurizer required. Add a featurizer to enable hybrid graph + descriptor mode.

from learnm8 import run_active_learning, CycleConfig

# SMILES-native (no featurizer)
results = run_active_learning(
    compound_pool='compounds.csv',
    oracle='oracle.csv',
    learner='chemprop',
    target_col='Activity',
    n_cycles=10,
    batch_fraction=0.01,
)

# Hybrid: graph + Mordred descriptors
results_hybrid = run_active_learning(
    compound_pool='compounds.csv',
    oracle='oracle.csv',
    learner='chemprop',
    target_col='Activity',
    featurizer='descriptors',
    n_cycles=10,
    batch_fraction=0.01,
)

Ensemble with Uncertainty

Ensembles estimate uncertainty via member disagreement (std dev across predictions).

from learnm8 import run_active_learning, CycleConfig

results = run_active_learning(
    compound_pool='compounds.csv',
    oracle='oracle.csv',
    learner='ensemble',
    target_col='Activity',
    featurizer='morgan',
    cycles=[
        CycleConfig('random',   n_cycles=1, batch_fraction=0.02),
        CycleConfig('ucb',      n_cycles=5, batch_fraction=0.005,
                    acquisition_params={'beta': 1.5}),
        CycleConfig('thompson', n_cycles=4, batch_fraction=0.005),
    ],
    random_state=42,
)

# Inspect uncertainty estimates from final cycle
last = results['cycle_metrics'][-1]
print(f"Has uncertainty: {last['has_uncertainty']}")
print(f"Mean uncertainty: {last['mean_uncertainty']}")

Score-Based Pruning

Remove unpromising compounds from the pool during the run to focus resources on the interesting region.

from learnm8 import run_active_learning, CycleConfig

results = run_active_learning(
    compound_pool='compounds.csv',
    oracle='oracle.csv',
    learner='gp',
    target_col='Activity',
    featurizer='morgan',
    cycles=[
        CycleConfig('random', n_cycles=1, batch_fraction=0.02),
        CycleConfig('ucb',    n_cycles=5, batch_fraction=0.005,
                    pruning_strategy='score',
                    pruning_params={'pruning_fraction': 0.3}),
        CycleConfig('greedy', n_cycles=4, batch_fraction=0.005),
    ],
    random_state=42,
)

Minimisation Campaign

Set score_direction='lower' to target the lowest predicted values (e.g., minimise toxicity or binding energy).

from learnm8 import run_active_learning, CycleConfig

results = run_active_learning(
    compound_pool='compounds.csv',
    oracle='oracle.csv',
    learner='rf',
    target_col='Toxicity',
    featurizer='descriptors',
    cycles=[
        CycleConfig('random', n_cycles=1, batch_fraction=0.02),
        CycleConfig('greedy', n_cycles=9, batch_fraction=0.005,
                    acquisition_params={'score_direction': 'lower'}),
    ],
)

Direct Feature Extraction

Extract features independently of the active learning loop.

from learnm8 import extract_features
from pathlib import Path

smiles = ['CCO', 'c1ccccc1', 'CC(=O)Oc1ccccc1C(=O)O']

# Binary fingerprint (packed storage, ~32x smaller than float32)
morgan_fp = extract_features(smiles, featurizer='morgan', cache_dir=Path('.cache'))

# Physicochemical descriptors
descriptors = extract_features(smiles, featurizer='descriptors',
                               cache_dir=Path('.cache'), show_progress=True)

# Optimised storage for tree learners (uint8 fast path)
fp_uint8 = extract_features(smiles, featurizer='morgan',
                             preferred_dtype='uint8')

print(morgan_fp.shape)    # (3, 2048)
print(descriptors.shape)  # (3, 1613)

Compound Pool Validation

Validate SMILES before starting an experiment.

from learnm8 import validate_compound_pool
import polars as pl

compounds = pl.read_csv('compounds.csv')
result = validate_compound_pool(
    compounds,
    n_jobs=-1,
    progress=True,
    target_col='Activity',
)

print(f"Valid:   {len(result.valid_compounds)}")
print(f"Invalid: {len(result.invalid_smiles)}")

if result.invalid_smiles:
    print("Invalid SMILES:")
    for idx, smi in zip(result.invalid_indices, result.invalid_smiles):
        print(f"  row {idx}: {smi}")

Accessing Results

results = run_active_learning(...)

# Final compounds DataFrame — 7 columns
df = results['compounds_df']
# Columns: ID, SMILES, status, labeled_cycle, selected_cycle, pruned_cycle, <target_col>

# Per-cycle metrics
for m in results['cycle_metrics']:
    print(m['cycle'], m['strategy'], m['n_labeled'], m['r2_score'])

# Aggregate summary
agg = results['aggregate_metrics']
print(agg['final_r2'], agg['best_r2_cycle'])

# Output files written
for path in results['saved_files']:
    print(path)

CLI Quick Reference

# Benchmark experiment
learnm8 run compounds.csv --target Activity --learner rf --featurizer morgan --n-cycles 10

# Production screening
learnm8 run compounds.csv scoring.py:score --target score --learner ensemble --n-cycles 20

# Custom strategy
learnm8 run compounds.csv --target Activity --learner gp --featurizer ecfp6 \
  --strategy ucb --acquisition-params '{"beta": 2.0}' --n-cycles 15

# Multi-stage schedule
learnm8 run compounds.csv --target Activity --learner gp --featurizer morgan \
  --cycles "random:0.02 ucb:0.005*7 greedy:0.005*2"

# Large-scale with shared cache
learnm8 run large_lib.csv --target Activity --learner rf --featurizer morgan \
  --cache-dir .shared_cache --output-format parquet \
  --n-cycles 10

# Force uncertainty even with greedy
learnm8 run compounds.csv --target Activity --learner gp --featurizer morgan \
  --strategy greedy --force-uncertainty --n-cycles 10

# Minimise (lower is better)
learnm8 run compounds.csv --target Toxicity --learner rf --featurizer descriptors \
  --strategy greedy --score-direction lower --n-cycles 10