Skip to content

Configuration Files

Configuration files provide a convenient way to specify all experiment parameters in a structured format, making experiments reproducible and version-controllable. LearnM8 supports both YAML and JSON configuration formats.

Overview

Configuration files are useful when:

  • Running multiple experiments with different parameter combinations
  • Ensuring reproducibility by version controlling experiment configurations
  • Managing complex parameter sets that would be unwieldy as CLI flags
  • Sharing experiments with collaborators
  • Documenting experimental protocols for publications

Configuration files support all parameters available in the run_active_learning() API, including advanced features like custom cycle specifications and acquisition parameters.

YAML Configuration Format

YAML is the recommended format for configuration files due to its readability and support for comments.

Complete Schema

# Input Data
compound_pool: "path/to/compounds.csv"
oracle: "path/to/oracle.csv" # or "module.py:function"
target_col: "Activity"

# Model Configuration
learner: "rf" # Learner shortcut string
featurizer: "morgan" # Required for non-GNN learners

# Cycle Configuration (choose one of these approaches)

# Option 1: Simple API (consistent batch sizes)
n_cycles: 10
batch_fraction: 0.01
strategy: "greedy"
initial_strategy: "random"

# Option 2: Explicit cycle list (advanced)
cycles:
  - strategy: "random"
    n_cycles: 1
    batch_fraction: 0.02
  - strategy: "greedy"
    n_cycles: 5
    batch_fraction: 0.01
  - strategy: "ucb"
    n_cycles: 4
    batch_fraction: 0.01
    acquisition_params:
      beta: 2.0

# Optimization Settings
score_direction: "higher" # or "lower"

# Output Configuration
output_dir: "results/experiment_001"
cache_dir: ".cache/shared" # Optional, defaults to output_dir/.cache

# Advanced Features
random_state: 42

# Chemprop Fine-Tuning (for Chemprop learners only)
enable_chemprop_fine_tuning: false

# Pruning Configuration
pruning_fraction: 0.3 # Optional, enables pruning if specified
pruning_strategy: "score" # Only supported strategy
pruning_params:
  score_direction: "higher" # Optional: overrides the top-level setting

# Acquisition Parameters (optional, strategy-specific)
acquisition_params:
  beta: 1.5 # for UCB

Simple Configuration Example

Minimal configuration for a standard experiment:

# experiment.yaml
compound_pool: "compounds.csv"
target_col: "Activity"
learner: "gp"
featurizer: "morgan"
n_cycles: 10
batch_fraction: 0.01

Advanced Configuration with Custom Cycles

Multi-strategy experiment with per-cycle control:

# advanced_experiment.yaml
compound_pool: "compound_library.csv"
oracle: "scoring_module.py:calculate_affinity"
target_col: "binding_score"
learner: "ensemble"
featurizer: "morgan"
score_direction: "lower"
random_state: 123

cycles:
  - strategy: "random"
    n_cycles: 1
    batch_fraction: 0.02
  - strategy: "ucb"
    n_cycles: 5
    batch_fraction: 0.01
    acquisition_params:
      beta: 2.0
  - strategy: "greedy"
    n_cycles: 4
    batch_fraction: 0.01

pruning_fraction: 0.2
pruning_strategy: "score"

output_dir: "results/ensemble_screening"
cache_dir: ".cache/shared"

Configuration with Pruning and Ensemble

Example using advanced features:

# pruning_ensemble_experiment.yaml
compound_pool: "large_library.csv"
target_col: "Activity"
learner: "mixed_ensemble"
featurizer: "descriptors"
score_direction: "higher"

cycles:
  - strategy: "random"
    n_cycles: 1
    batch_fraction: 0.01
  - strategy: "ucb"
    n_cycles: 8
    batch_fraction: 0.005
    acquisition_params:
      beta: 1.5
  - strategy: "simulated_annealing"
    n_cycles: 3
    batch_fraction: 0.01

pruning_fraction: 0.3
pruning_strategy: "score"
pruning_params:
  score_direction: "higher"

cache_dir: ".cache/global"
random_state: 42

JSON Configuration Format

JSON format is also supported, with identical schema to YAML but different syntax.

Complete JSON Example

{
  "compound_pool": "compounds.csv",
  "oracle": "oracle.csv",
  "target_col": "Activity",
  "learner": "gp",
  "featurizer": "morgan",
  "n_cycles": 10,
  "batch_fraction": 0.01,
  "strategy": "greedy",
  "initial_strategy": "random",
  "score_direction": "higher",
  "output_dir": "results/experiment_001",
  "cache_dir": ".cache/shared",
  "random_state": 42
}

JSON with Custom Cycles

{
  "compound_pool": "compound_library.csv",
  "oracle": "scoring_module.py:calculate_affinity",
  "target_col": "binding_score",
  "learner": "ensemble",
  "featurizer": "morgan",
  "score_direction": "lower",
  "cycles": [
    {
      "strategy": "random",
      "n_cycles": 1,
      "batch_fraction": 0.02
    },
    {
      "strategy": "ucb",
      "n_cycles": 5,
      "batch_fraction": 0.01,
      "acquisition_params": {
        "beta": 2.0
      }
    },
    {
      "strategy": "greedy",
      "n_cycles": 4,
      "batch_fraction": 0.01
    }
  ],
  "pruning_fraction": 0.2,
  "pruning_strategy": "score",
  "output_dir": "results/ensemble_screening",
  "cache_dir": ".cache/shared",
  "random_state": 123
}

JSON with All Features

{
  "compound_pool": "large_library.csv",
  "oracle": "docking_oracle.py:dock_compounds",
  "target_col": "docking_score",
  "learner": "chemprop_ensemble",
  "featurizer": "descriptors",
  "score_direction": "lower",
  "enable_chemprop_fine_tuning": true,
  "cycles": [
    {
      "strategy": "random",
      "n_cycles": 1,
      "batch_fraction": 0.01
    },
    {
      "strategy": "ucb",
      "n_cycles": 8,
      "batch_fraction": 0.005,
      "acquisition_params": {
        "beta": 1.5
      }
    },
    {
      "strategy": "simulated_annealing",
      "n_cycles": 3,
      "batch_fraction": 0.01
    }
  ],
  "pruning_fraction": 0.3,
  "pruning_strategy": "score",
  "pruning_params": {
    "score_direction": "lower"
  },
  "acquisition_params": {
    "beta": 1.5
  },
  "output_dir": "results/chemprop_screening",
  "cache_dir": ".cache/global",
  "random_state": 42
}

Loading Configurations

Using the CLI

Load a configuration file using the --config flag:

# Load YAML configuration
learnm8 run --config experiment.yaml

# Load JSON configuration
learnm8 run --config experiment.json

The configuration file provides default values for all parameters. When loaded, LearnM8 will display the configuration and begin the experiment.

Combining Config Files with CLI Flags

CLI flags override configuration file values when explicitly provided:

# Use config but override learner and output directory
learnm8 run --config experiment.yaml \
  --learner ensemble \
  -o results/modified_experiment

Precedence Rules

Parameter values are determined in the following order (later overrides earlier):

  1. Configuration file defaults (if --config is provided)
  2. CLI argument defaults (defined in argparse)
  3. Explicit CLI flags (user-provided values)

Example:

# config.yaml
learner: "rf"
n_cycles: 10
output_dir: "results/default"
# Override learner and output_dir, keep n_cycles from config
learnm8 run --config config.yaml \
  --learner gp \
  -o results/custom

Result:

  • learner: "gp" (CLI override)
  • n_cycles: 10 (from config)
  • output_dir: "results/custom" (CLI override)

Python API with Config Files

Load and use configuration dictionaries programmatically:

import yaml
from pathlib import Path
from learnm8 import run_active_learning

# Load configuration
config_path = Path("experiment.yaml")
with open(config_path) as f:
    config = yaml.safe_load(f)

# Run experiment with config
results = run_active_learning(**config)

Override specific parameters:

import yaml
from learnm8 import run_active_learning

# Load base configuration
with open("base_config.yaml") as f:
    config = yaml.safe_load(f)

# Override specific parameters
config['learner'] = 'ensemble'
config['output_dir'] = 'results/modified'

# Run experiment
results = run_active_learning(**config)

Configuration Best Practices

Version Control

Configuration files are ideal for version control:

# Track experiment configurations
git add experiments/config_*.yaml
git commit -m "Add configuration for ensemble comparison"

Benefits:

  • Reproducibility: Exact experiment parameters preserved
  • Collaboration: Share configurations with team members
  • Tracking: Document experimental protocol evolution
  • Comparison: Diff configs to understand parameter changes

Naming Conventions

Use descriptive, systematic naming for configuration files:

experiments/
├── baseline_rf_morgan.yaml
├── ensemble_ucb_beta2.yaml
├── chemprop_finetune_intensive.yaml
├── pruning_30pct_uncertainty.yaml
└── production_screening_gp.yaml

Recommended naming pattern:

{experiment_type}_{key_feature}_{variation}.yaml

Comments in YAML

YAML supports comments (JSON does not), making it ideal for documenting parameter choices:

# Baseline Random Forest experiment with Morgan fingerprints
compound_pool: "compounds.csv"
target_col: "Activity"

# Using RF for fast baseline comparison
learner: "rf"
featurizer: "morgan" # 2048-bit Morgan fingerprints

# Conservative exploration-exploitation balance
cycles:
  - strategy: "random"
    n_cycles: 1
    batch_fraction: 0.02 # Larger initial batch for diversity
  - strategy: "ucb"
    n_cycles: 5
    batch_fraction: 0.01 # Standard batch size
    acquisition_params:
      beta: 1.5 # Moderate exploration weight
  - strategy: "greedy"
    n_cycles: 4
    batch_fraction: 0.01 # Exploitation phase

# Reproducibility seed
random_state: 42

When to Use Config Files vs CLI

Use configuration files when:

  • Running parameter sweeps (create multiple config files)
  • Complex experiments with many parameters
  • Reproducibility is critical (publications, collaborations)
  • Sharing experiments with collaborators
  • Long-term projects requiring documentation

Use CLI directly when:

  • Quick exploratory experiments with few parameters
  • One-off tests not requiring documentation
  • Interactive development and debugging
  • Simple experiments with default parameters

Configuration File Organization

Organize configurations by experiment type:

experiments/
├── benchmarking/
│   ├── ada_rf.yaml
│   ├── ada_gp.yaml
│   └── ada_ensemble.yaml
├── production/
│   ├── screening_campaign_01.yaml
│   └── screening_campaign_02.yaml
├── parameter_sweeps/
│   ├── ucb_beta_0.5.yaml
│   ├── ucb_beta_1.0.yaml
│   ├── ucb_beta_2.0.yaml
│   └── ucb_beta_3.0.yaml
└── ablation_studies/
    ├── no_pruning.yaml
    ├── pruning_20pct.yaml
    └── pruning_40pct.yaml

Parameter Reference

All parameters from run_active_learning() are supported in configuration files.

Core Parameters

Parameter Type Description
compound_pool str/Path CSV file with compound library (ID, SMILES columns)
oracle str/Path Oracle specification (CSV file or module.py:function)
target_col str Target property column name
learner str Learner shortcut (rf, gp, ensemble, etc.)
featurizer str Molecular featurizer (morgan, maccs, ecfp6, descriptors)

Cycle Configuration (Simple API)

Parameter Type Default Description
n_cycles int 10 Number of active learning cycles
batch_fraction float 0.01 Fraction of pool to label per cycle
strategy str "greedy" Acquisition strategy for cycles 1+
initial_strategy str "random" Acquisition strategy for cycle 0

Cycle Configuration (Advanced API)

Parameter Type Description
cycles list[dict] List of cycle configurations with strategy, n_cycles, batch_fraction

Cycle dictionary structure:

- strategy: "ucb"
  n_cycles: 5
  batch_fraction: 0.01
  acquisition_params: # Optional
    beta: 2.0
  pruning_strategy: "score" # Optional
  pruning_params: # Optional
    pruning_fraction: 0.3

Common Parameters

Parameter Type Default Description
score_direction str "higher" Optimization direction (higher or lower)
output_dir str/Path None Output directory (auto-generated if None)
cache_dir str/Path None Feature cache directory (output_dir/.cache if None)
random_state int 42 Random seed for reproducibility

Advanced Features

Parameter Type Default Description
enable_chemprop_fine_tuning bool False Enable fine-tuning for Chemprop models
pruning_fraction float None Fraction to prune per cycle (0.0-0.9)
pruning_strategy str None Pruning method (only "score" is supported)
pruning_params dict None Additional pruning parameters
acquisition_params dict None Acquisition strategy parameters, e.g. beta for UCB

Complete Example Configurations

Benchmark Comparison Study

# benchmark_rf_vs_gp.yaml
compound_pool: "benchmark_datasets/ADA.csv"
target_col: "Activity"
featurizer: "morgan"
score_direction: "higher"

# Will run with both learners in separate experiments
learner: "rf" # or "gp"

cycles:
  - strategy: "random"
    n_cycles: 1
    batch_fraction: 0.02
  - strategy: "greedy"
    n_cycles: 9
    batch_fraction: 0.01

cache_dir: ".cache/benchmark"
random_state: 42

Production Screening Campaign

# production_screening.yaml
compound_pool: "screening_library_100k.csv"
oracle: "docking_pipeline.py:dock_and_score"
target_col: "docking_score"
learner: "mc_dropout"
featurizer: "descriptors"
score_direction: "lower"

cycles:
  - strategy: "random"
    n_cycles: 1
    batch_fraction: 0.001 # 100 compounds from 100k
  - strategy: "ucb"
    n_cycles: 10
    batch_fraction: 0.0005 # 50 compounds per cycle
    acquisition_params:
      beta: 2.0
  - strategy: "greedy"
    n_cycles: 5
    batch_fraction: 0.0005

pruning_fraction: 0.4
pruning_strategy: "score"
pruning_params:
  score_direction: "higher"

cache_dir: ".cache/production"
output_dir: "results/screening_campaign_001"
random_state: 123

Chemprop with Fine-Tuning

# chemprop_finetuning.yaml
compound_pool: "compounds.csv"
target_col: "Activity"
learner: "chemprop_ensemble"
featurizer: "descriptors" # Hybrid mode
enable_chemprop_fine_tuning: true

cycles:
  - strategy: "random"
    n_cycles: 1
    batch_fraction: 0.02
  - strategy: "ucb"
    n_cycles: 8
    batch_fraction: 0.01
    acquisition_params:
      beta: 1.5
  - strategy: "greedy"
    n_cycles: 3
    batch_fraction: 0.01

cache_dir: ".cache/chemprop"
random_state: 42

Validation and Debugging

Validating Configuration Files

Test configuration file syntax before running:

# YAML validation
python -c "import yaml; yaml.safe_load(open('config.yaml'))"

# JSON validation
python -c "import json; json.load(open('config.json'))"

Common Configuration Errors

Missing required parameters:

# ERROR: Missing target_col
compound_pool: "compounds.csv"
learner: "rf"

Conflicting cycle specifications:

# ERROR: Cannot specify both simple and advanced API
n_cycles: 10
cycles: # Conflicts with n_cycles
  - strategy: "random"
    n_cycles: 1

Invalid parameter types:

# ERROR: batch_fraction must be float
batch_fraction: "0.01" # Should be: 0.01

Testing Configurations

Test configurations with small datasets before production runs:

# Test with subset of data
learnm8 run test_subset.csv --config production_config.yaml \
  -o results/config_test