Analyzes chemical libraries by scaffold using Bemis-Murcko scaffolds, generic frameworks, cyclic skeletons, matched molecular pair (MMP) analysis via mmpdb, R-group decomposition, Free-Wilson analysis, scaffold hopping, and chemotype-aware ML train/test splits. Use when identifying chemotype clusters in a library, deriving SAR transformation rules, decomposing series into R-groups, performing scaffold-balanced QSAR splits, or planning analog campaigns.
Analyzes chemical libraries by scaffold using Bemis-Murcko scaffolds, generic frameworks, cyclic skeletons, matched molecular pair (MMP) analysis via mmpdb, R-group decomposition, Free-Wilson analysis, scaffold hopping, and chemotype-aware ML train/test splits. Use when identifying chemotype clusters in a library, deriving SAR transformation rules, decomposing series into R-groups, performing scaffold-balanced QSAR splits, or planning analog campaigns.
Before using code patterns, verify installed versions match. If versions differ:
Python: pip show <package> then help(module.function) to check signatures
If code throws ImportError, AttributeError, or TypeError, introspect the installed
package and adapt the example to match the actual API rather than retrying.
Scaffold Analysis
Analyze chemical libraries by their underlying scaffolds. Bemis-Murcko (1996) is the canonical scaffold decomposition: ring systems + linkers, with all R-groups stripped. Generic framework + cyclic skeleton are progressively-more-abstract views. Scaffold analysis underpins QSAR train/test splits (preventing data leakage), library diversity assessment, chemotype clustering, R-group decomposition for SAR modeling, and matched molecular pair analysis (MMPA). The choice of scaffold representation determines whether two compounds are "the same series" -- a critical decision for medicinal chemistry workflows.
For reaction-based enumeration and Free-Wilson, see chemoinformatics/reaction-enumeration. For scaffold-hopping via fingerprints, see chemoinformatics/similarity-searching. For 3D shape-based scaffold hopping, see chemoinformatics/shape-similarity.
Scaffold Representation Taxonomy
Representation
Origin
Definition
Use case
Fails when
Bemis-Murcko scaffold
Bemis & Murcko 1996
Ring systems + linkers, R-groups stripped
Default chemotype identifier
Linear molecules (no rings) -> empty scaffold
Generic framework
Bemis & Murcko 1996
Bemis-Murcko with all atoms set to C, all bonds single
For QSAR / ML, random train/test split causes data leakage: compounds from the same chemotype (analogs in same series) end up in both. Bemis-Murcko split puts entire scaffolds in train or test, never both.
from rdkit.Chem.Scaffolds import MurckoScaffold
defscaffold_split(df, smiles_col='smiles', train_frac=0.8, seed=42):
import random
rng = random.Random(seed)
scaffolds = defaultdict(list)
invalid_positions = []
for pos, smi inenumerate(df[smiles_col].tolist()):
mol = Chem.MolFromSmiles(smi)
if mol isNone:
invalid_positions.append(pos)
continue
scaff = Chem.MolToSmiles(MurckoScaffold.GetScaffoldForMol(mol))
scaffolds[scaff].append(pos)
if invalid_positions:
raise ValueError(f'Invalid SMILES at row positions: {invalid_positions}')
scaffold_sets = list(scaffolds.values())
rng.shuffle(scaffold_sets)
scaffold_sets.sort(key=lambda x: len(x), reverse=True)
n_total = sum(len(s) for s in scaffold_sets)
n_train = int(n_total * train_frac)
iflen(scaffold_sets) < 2:
raise ValueError('A scaffold split requires at least two scaffolds')
train_idx = list(scaffold_sets[0])
test_idx = []
for i, scaff_set inenumerate(scaffold_sets[1:], start=1):
ifnot test_idx and i == len(scaffold_sets) - 1:
test_idx.extend(scaff_set)
elifabs(len(train_idx) + len(scaff_set) - n_train) < abs(len(train_idx) - n_train):
train_idx.extend(scaff_set)
else:
test_idx.extend(scaff_set)
return df.iloc[train_idx], df.iloc[test_idx]
Effect on benchmark metrics: A scaffold split often produces different performance from a random split because it tests transfer across scaffold groups. The size and meaning of the gap are dataset- and deployment-dependent; it is not a direct universal measure of memorization.
Caveat: Bemis-Murcko split is one scaffold-split; for production ML, consider time split (newer compounds in test) or activity-cliff-balanced split.
Class-imbalanced datasets: Scaffold-only assignment can yield skewed class distributions. Chemprop's scaffold_balanced split balances scaffold-group sizes; it is not label-stratified. If both group isolation and label balance are required, use a validated group-aware stratification procedure such as StratifiedGroupKFold where its assumptions fit, then audit every fold for scaffold overlap and endpoint balance.
R-Group Decomposition
Goal: Given a defined scaffold and a set of analog compounds, extract the R-group at each numbered attachment point into a tabular SAR matrix.
from rdkit.Chem import rdRGroupDecomposition as rgd
defdecompose_series(compounds, scaffold_smiles_with_R):
scaffold = Chem.MolFromSmiles(scaffold_smiles_with_R)
if scaffold isNone:
raise ValueError('Invalid scaffold SMARTS/SMILES')
parsed = [(i, Chem.MolFromSmiles(s)) for i, s inenumerate(compounds)]
invalid = [i for i, mol in parsed if mol isNone]
if invalid:
raise ValueError(f'Invalid compound SMILES at positions: {invalid}')
mols = [mol for _, mol in parsed]
decomp, unmatched = rgd.RGroupDecompose([scaffold], mols, asSmiles=True)
unmatched_set = set(unmatched)
matched_positions = [i for i inrange(len(mols)) if i notin unmatched_set]
return decomp, matched_positions, list(unmatched)
scaffold = 'c1ccc(C(=O)N[*:1])cc1-[*:2]'
compounds = ['c1ccc(C(=O)NCC)cc1F', 'c1ccc(C(=O)NCCC)cc1Cl']
table = decompose_series(compounds, scaffold)
Output: list of {'Core': scaffold, 'R1': r1_smiles, 'R2': r2_smiles} dicts. Used for Free-Wilson analysis (see reaction-enumeration skill).
Matched Molecular Pair Analysis (MMPA) via mmpdb
Goal: Mine a SAR dataset for substructure transformations and their associated activity changes.
Approach: Fragment all compounds into core + variable side; index pairs differing by one transformation; report delta(activity) per transformation.
mmpdb fragment data.smi -o data.fragments
mmpdb index data.fragments -o data.mmpdb
mmpdb transform --smiles 'COc1ccccc1' --property pIC50 data.mmpdb
Output: ranked transformations with delta(pIC50), N pairs, confidence.
Interpret transformation effects from pair count, chemical-context diversity, dependence among pairs, uncertainty intervals, and prospective validation. Do not convert a universal pair-count/effect-size table into reliability labels.
Context-Based MMPA
Classical MMPA: "Me -> F always +0.5 log units."
Context-based MMPA: "Me -> F adjacent to amide is +0.5; Me -> F adjacent to ester is -0.1."
Matched-pair effects can depend strongly on the local chemical environment, so report the transformation together with its attachment-point context rather than treating a global mean as universal (Raut & Dixit 2025). Use mmpdb's stored environments or a custom stratified analysis to compare context-specific effects.
Scaffold Hopping
Goal: Find compounds with different scaffold but similar 3D shape / pharmacophore / activity.
Method
Approach
Tools
2D similarity with FCFP4
Functional-class fingerprint Tanimoto
similarity-searching skill
3D shape (ROCS)
Tanimoto on shape + color volumes
shape-similarity skill
Pharmacophore
Common pharmacophore features
pharmacophore-modeling skill
Maximum Common Substructure (MCS)
Largest shared substructure
similarity-searching skill (rdFMCS)
Deep scaffold hopping
Conditional molecular generation
DeepHop (Zheng et al. 2021)
For systematic scaffold-hop discovery, combine:
Find target's bioactive series
Compute 3D pharmacophore from bound conformer
ROCS / pharmacophore search against vendor catalogs
Filter to compounds with Bemis-Murcko scaffold NOT in training data
Series Detection
Goal: Identify "analog series" within a library -- compounds sharing a scaffold + co-varying R-groups.
defdetect_series(smiles_list, min_size=3):
clusters = scaffold_clusters(smiles_list)
series = {scaff: cmpds for scaff, cmpds in clusters.items()
iflen(cmpds) >= min_size}
return series
Series counts depend on library provenance, standardization, scaffold definition, and minimum size. Report the observed distribution and use series as one possible unit for SAR analysis.
Per-Tool Failure Modes
Bemis-Murcko -- linear molecule yields empty
Trigger: Compound has no rings (e.g., fatty acid, simple amine).
Mechanism: Bemis-Murcko strips R-groups; no rings = nothing remains.
Symptom: Scaffold is empty string; molecules cluster together as "no scaffold".
Fix: For linear-rich libraries, augment with linear chain length / functional group features.
Bemis-Murcko -- spiro / bridged ring confusion
Trigger: Compound has spiro or bridged ring system.
Mechanism: All ring atoms included; result is the entire ring system without R-groups.
Symptom: Apparently different drugs share a "scaffold" because of common spiro center.
Fix: Validate visually; use generic framework for topology-only comparison.
Generic framework -- loses heteroatom info
Trigger: Distinguishing pyridine vs benzene scaffolds.
Mechanism:MakeScaffoldGeneric sets all atoms to C.
Symptom: Pyridine and benzene scaffolds reported as identical.
Fix: Use Bemis-Murcko (heteroatoms preserved); generic framework for topology only.
Scaffold split -- imbalanced classes
Trigger: Library has many singletons + few large scaffolds.
Mechanism: Large scaffolds dominate; greedy assignment puts them in train.
Symptom: Test set is mostly singleton scaffolds; metrics misleading.
Fix: Use stratified scaffold split (balance test classes); or scaffold-balanced cross-validation.
MMPA -- low pair count for novel transformations
Trigger: Transformation rare in dataset.
Mechanism: Need enough pairs to estimate delta(activity).
Symptom: Transformation reports N=2 with very large delta.
Fix: Report uncertainty and context diversity, avoid overinterpreting sparse transformations, and seek additional matched evidence where appropriate.
R-group decomposition -- ambiguous match
Trigger: Multiple positions in scaffold could match same R-group.
Mechanism: Multiple core embeddings, symmetry, and unlabeled attachment choices can yield assignments that differ from the medicinal-chemistry convention.
Symptom: R1/R2 columns mixed up.
Fix: Specify labeled attachment points, inspect the returned rows and unmatched indices, and use RGroupDecompositionParameters for the intended matching/alignment behavior.
Reconciliation: Scaffold Definition Disagreements
Concept
Definition A
Definition B
Pick which
Bemis-Murcko scaffold
Atoms in rings + linkers
Same
RDKit default
Generic framework
All C, all single bonds
All C, original bonds
MakeScaffoldGeneric implements the first; preserve bond orders with an explicit custom transformation
Cyclic skeleton
Only ring atoms
Only ring atoms, generic
Implement explicitly; it is not an RDKit Murcko flag
"Series"
Same Bemis-Murcko
Tanimoto > 0.8 + same MW
Bemis-Murcko for SAR; Tanimoto for screening
For ML splits: Bemis-Murcko. For library diversity: Bemis-Murcko + cluster size. For series detection: Bemis-Murcko + R-group decomposition.
Common Errors
Symptom
Cause
Fix
Murcko scaffold includes unexpected linker atoms
Bemis-Murcko linkers connect ring systems by definition
Inspect the definition; for hierarchical networks use rdScaffoldNetwork.ScaffoldNetworkParams with CreateScaffoldNetwork
Singleton scaffolds dominate library
Aggressive standardization
Check for tautomer-induced scaffold variation; canonicalize first
R-group decomposition empty
Mol doesn't match scaffold
Use FMCS to find actual shared core
mmpdb missing transformations
Cores too restrictive
Try smaller core requirement
Scaffold split gives all to train
Few scaffolds; large clusters
Add singleton-spread strategy; use Murcko-and-Linker variant
Generic framework same for different drugs
Stripped heteroatom info
Use Bemis-Murcko (preserves heteroatoms)
MakeScaffoldGeneric error
RDKit version issue
RDKit 2024.09+ uses Chem.Scaffolds.MurckoScaffold
References
Bemis GW, Murcko MA. J. Med. Chem. 39:2887-2893 (1996) -- original scaffold framework (DOI 10.1021/jm9602928).
Hu, Stumpfe & Bajorath, J. Med. Chem. 60:1238-1246 (2017), DOI 10.1021/acs.jmedchem.6b01437 -- modern scaffold hopping review.
Hussain J, Rea C. J. Chem. Inf. Model. 50:339-348 (2010) -- MMPA core method (DOI 10.1021/ci900450m).
Raut & Dixit, RSC Med. Chem. 16:3281-3290 (2025), DOI 10.1039/D4MD01012D -- local-environment effects in matched molecular pairs.
Zheng et al., J. Cheminformatics 13:87 (2021), DOI 10.1186/s13321-021-00565-5 -- DeepHop conditional scaffold hopping.
Yang K et al., J. Chem. Inf. Model. 59:3370-3388 (2019) -- Chemprop molecular-property prediction (DOI 10.1021/acs.jcim.9b00237).
