molecular-descriptors

Version Compatibility

Reference examples tested with: RDKit 2024.09+, numpy 1.26+, pandas 2.2+, mapchiral 0.1+ (MAP4), mhfp 1.9+, molfeat 0.10+.

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.

Molecular Descriptors

Hard rules

1. No fabricated citations. Every cited work must resolve to a verifiable
2. No claim without provenance. Every quantitative or factual claim
3. No silent failure. Every script invocation, API call, or tool use must declare its exit status and what to do on non-zero. A skill that silently swallows errors is a violation.

When to use

Load this skill when the user asks a question that matches its declared trigger conditions (see the frontmatter description for the most common ones). Do not load it for questions outside its scope — defer to the appropriate ORS skill instead.

When NOT to use

Do not load this skill if the question is in a sibling skill's domain (see ## Cross-references), if the user explicitly asks for a different tool, or if the task is outside the skill's declared category.

Fingerprint Taxonomy

Decision: For drug-like similarity ranking, use ECFP4 2048 bit; established baseline, fast, well-understood. For diverse libraries (>1M compounds, metabolomics, peptides), MHFP6 outperforms ECFP4 on analog recovery (Probst & Reymond 2018). For scaffold hopping, AtomPair beats ECFP4 on retrospective benchmarks but loses on retrospective single-target.

Bit vs Count Vectors

from rdkit import Chem
from rdkit.Chem import AllChem

mol = Chem.MolFromSmiles('CCO')

ecfp4_bit = AllChem.GetMorganFingerprintAsBitVect(mol, radius=2, nBits=2048)
ecfp4_count = AllChem.GetHashedMorganFingerprint(mol, radius=2, nBits=2048)
ecfp4_sparse = AllChem.GetMorganFingerprint(mol, radius=2)

Morgan / ECFP Radius Math

ECFP-X notation: X is the diameter in bonds. RDKit's radius parameter is half of X.

Trade-off: Larger radius captures more specific local environment but inflates bit-collision rate at fixed nBits. For QSAR with <10k compounds, ECFP4 2048 is the established default (Rogers & Hahn 2010; MoleculeNet benchmarks Wu 2018). For large libraries (>1M), use nBits=4096 or unhashed sparse representation to reduce ~1-5% bit-collision rate (O'Boyle 2016).

FCFP vs ECFP

FCFP (Functional-Class) uses atom invariants based on pharmacophore role (donor, acceptor, hydrophobe, aromatic, halogen, basic, acidic) instead of atom identity. Trades atom-specificity for functional-equivalence.

ecfp4 = AllChem.GetMorganFingerprintAsBitVect(mol, radius=2, useFeatures=False)
fcfp4 = AllChem.GetMorganFingerprintAsBitVect(mol, radius=2, useFeatures=True)

When to use FCFP4: Scaffold-hopping campaigns, pharmacophore-driven similarity, cross-target activity prediction.

When to use ECFP4: Within-series QSAR, lead optimization, when chemotype identity matters.

molfeat: Pluggable Featurization

molfeat (Datamol/Molecular AI) wraps RDKit, Mordred, Vina, and hand-crafted transformers behind a uniform Transformer interface. It is the right choice when you need to swap featurizations programmatically (e.g. for a benchmark or a notebook exploration) rather than hardcoding the RDKit calls.

from molfeat.trans.fp import FPVecTransformer

ecfp4 = FPVecTransformer(kind='ecfp', length=2048, radius=2)
fcfp4 = FPVecTransformer(kind='fcfp', length=2048, radius=2)
ap = FPVecTransformer(kind='ap', length=2048)
mhfp6 = FPVecTransformer(kind='mhfp', length=2048, radius=3)

# X is a numpy array, y is a list of mols or SMILES
X = ecfp4(list_of_mols)

For large fingerprints (MHFP6, AtomPair) or large libraries, molfeat avoids the boilerplate of building fingerprints one molecule at a time.

3D Descriptors and Conformer Dependence

Conformer-dependent descriptors (asphericity, eccentricity, principal moments of inertia, RDF) require a generated 3D structure. A single conformer is rarely sufficient: descriptor variance across the conformer ensemble can exceed the descriptor signal.

Goal: Compute 3D shape descriptors over a conformer ensemble rather than from a single (possibly unrepresentative) conformer.

Approach: Add explicit hydrogens, embed N conformers with ETKDGv3, MMFF-optimize them all, then evaluate the descriptor across each conformer for downstream averaging.

from rdkit.Chem import AllChem, Descriptors3D

mol = Chem.MolFromSmiles('CCCCO')
mol = Chem.AddHs(mol)

params = AllChem.ETKDGv3()
params.randomSeed = 42
n = AllChem.EmbedMultipleConfs(mol, numConfs=20, params=params)
AllChem.MMFFOptimizeMoleculeConfs(mol)

asphericities = [Descriptors3D.Asphericity(mol, confId=c) for c in range(n)]

Decision: For QSAR / ML, compute over a conformer ensemble (n=20-100) and report mean or Boltzmann-weighted average. Single-conformer 3D descriptors are unreliable.

Partial Charge Methods

from rdkit.Chem import AllChem

AllChem.ComputeGasteigerCharges(mol)
for atom in mol.GetAtoms():
    print(atom.GetIdx(), atom.GetPropsAsDict().get('_GasteigerCharge', None))

Critical: Charge method must match downstream. Gasteiger charges in an AMBER MD run violate the assumptions of the protein force field.

MAP4 and MHFP6 for Diverse Libraries

For libraries spanning drug-like + natural products + peptides + metabolites, ECFP4 saturates Tanimoto similarity (most pairs report 0.1-0.3, hard to rank). MAP4 and MHFP6 use MinHash + atom-pair / circular substructures and discriminate better.

from mhfp.encoder import MHFPEncoder

encoder = MHFPEncoder
mhfp6 = encoder.encode(mol, radius=3)

MHFP6 distance is Jaccard on MinHash, not standard Tanimoto. Use MHFPEncoder.distance(fp1, fp2).

Physicochemical Descriptors

Goal: Compute a standard physicochemical descriptor panel for drug-likeness filtering and QSAR features.

Approach: Combine RDKit Descriptors, Lipinski, and QED calls into a single dict so the caller gets MW, LogP, HBD/HBA, TPSA, rotatable bonds, aromatic rings, fraction sp3, and QED in one pass.

from rdkit.Chem import Descriptors, Lipinski, QED

def physchem(mol):
    return {
        'MolWt': Descriptors.MolWt(mol),
        'MolLogP': Descriptors.MolLogP(mol),
        'HBD': Lipinski.NumHDonors(mol),
        'HBA': Lipinski.NumHAcceptors(mol),
        'TPSA': Descriptors.TPSA(mol),
        'RotBonds': Lipinski.NumRotatableBonds(mol),
        'AromRings': Lipinski.NumAromaticRings(mol),
        'FractionCSP3': Descriptors.FractionCSP3(mol),
        'QED': QED.qed(mol),
    }

Drug-Likeness Rule Sets

Use case: Apply Ro5/Veber as a screening filter, not a hard cutoff. ~30% of marketed oral drugs violate at least one Ro5 rule (analyzed by Doak 2014). For oncology indications, Ro5 deviation is common and acceptable.

QED (Weighted Drug-Likeness)

QED (Bickerton 2012) is a single-number drug-likeness measure (0-1) combining 8 properties (MW, LogP, HBD, HBA, PSA, RotBonds, AromaticRings, structural alerts) via desirability functions.

Caveat: QED is trained on FDA-approved drugs; it under-rates fragment-like and natural-product-like molecules. Do not use as the sole drug-likeness filter for fragment screens or natural-product libraries.

Common Errors

References

• Rogers & Hahn, J. Chem. Inf. Model. 50:742 -- ECFP / Morgan fingerprints.
• Probst & Reymond, J. Cheminformatics 10:66 -- MHFP6 fingerprint.
• Capecchi et al., J. Cheminformatics 12:43 -- MAP4 fingerprint.
• Bickerton et al., Nat. Chem. 4:90 -- QED weighted drug-likeness.
• Lipinski et al., Adv. Drug Deliv. Rev. 23:3 -- Rule of 5.
• Veber et al., J. Med. Chem. 45:2615 -- Oral bioavailability rules.
• Lovering et al., J. Med. Chem. 52:6752 -- Fraction sp3 / escape from flatland.

Related Skills

• chemoinformatics/molecular-io - Parse molecules before featurization
• chemoinformatics/molecular-standardization - Canonicalize before fingerprinting
• chemoinformatics/conformer-generation - Generate 3D for conformer-dependent descriptors
• chemoinformatics/similarity-searching - Use fingerprints for similarity ranking
• chemoinformatics/qsar-modeling - ML using these descriptors as features
• chemoinformatics/admet-prediction - Filter by drug-likeness criteria"

Cross-references

Other skills in this category:

• admet-prediction
• conformer-generation
• covalent-design
• docking-rescoring
• free-energy-calculations
• generative-design
• molecular-io
• molecular-standardization
• pharmacophore-modeling
• pose-validation
• protac-degraders
• qsar-modeling
• retrosynthesis
• scaffold-analysis
• shape-similarity
• similarity-searching
• substructure-search
• virtual-screening

Changelog

• 1.1.0 (migration) — Bulk-migrated to v0.4.0 schema: canonical metadata block, base Hard rules, Cross-references. Body content unchanged; author should review and fill in any domain-specific extensions to the Hard rules.
• 1.0.0 — Initial release.