🧩 scaffoldsplitlab

Leakage-aware train/val/test splitting for molecular machine learning.

---

Overview

scaffoldsplitlab splits molecular datasets into training, validation, and test sets using:

• Scaffold-based splitting — groups molecules by Murcko scaffold and assigns whole scaffolds to the same split, giving a more realistic estimate of generalization to novel chemical scaffolds. (Requires optional RDKit.)
• Random splitting — standard split, optionally stratified by a label column.
• Hash-based fallback — deterministic split using SMILES hashing when RDKit is unavailable.

Every split can be checked for cross-split leakage (duplicate molecules appearing in multiple splits) before it reaches your model.

Installation

Requires Python ≥ 3.10.

# From source (recommended for now)
git clone https://github.com/SaveenaSolanki/scaffoldsplitlab.git
cd scaffoldsplitlab

# Basic install (random splitting only)
pip install -e ".[dev]"

# With RDKit support (scaffold splitting)
pip install -e ".[dev,rdkit]"

PyPI release is planned. For now, install from source.

Quick Start

# Random split
scaffold-split --input molecules.csv --method random

# Scaffold split (requires RDKit)
scaffold-split --input molecules.csv --method scaffold

# Stratified random split
scaffold-split --input molecules.csv --method random --label-col label

# Custom fractions
scaffold-split --input molecules.csv --train 0.7 --val 0.15 --test 0.15 --seed 123

Run the demo:

bash examples/run_demo.sh

CLI Reference

scaffold-split [OPTIONS]

Options:
  -i, --input PATH       Input CSV file (required)
  -s, --smiles-col TEXT  SMILES column name [default: smiles]
  -l, --label-col TEXT   Label column (for stratification)
  -m, --method TEXT      Split method: 'random' or 'scaffold' [default: scaffold]
  --train FLOAT          Training fraction [default: 0.8]
  --val FLOAT            Validation fraction [default: 0.1]
  --test FLOAT           Test fraction [default: 0.1]
  --seed INTEGER         Random seed [default: 42]
  -o, --out PATH         Output CSV path [default: split_output.csv]

Python API

from scaffoldsplitlab.core import scaffold_split, random_split, check_split_leakage
from scaffoldsplitlab.io import read_csv, write_csv

df = read_csv("molecules.csv")
result = scaffold_split(df, smiles_col="smiles", train_frac=0.8, val_frac=0.1, test_frac=0.1)
write_csv(result, "split_output.csv")

# Check for duplicate SMILES across splits
leaks = check_split_leakage(result, smiles_col="smiles")
print(leaks)  # {} if no leakage

Development

git clone https://github.com/SaveenaSolanki/scaffoldsplitlab.git
cd scaffoldsplitlab
pip install -e ".[dev,rdkit]"
pytest
ruff check src/ tests/

Data & Privacy

All computation is local. No telemetry, analytics, or network calls. The example dataset (examples/demo_input.csv) contains 15 small molecules commonly used in cheminformatics tutorials and includes no proprietary or sensitive information.

License

MIT — part of the CompBio Toolkit Suite.