orthonym.perception.natural_products#

Note

Internal API. Names and behaviour may change between releases.

Natural product scaffold detection via RDKit substructure matching.

IUPAC: Retained names for natural product ring systems (steroids, terpenoids, alkaloids). These parent scaffolds have IUPAC-recommended retained names that take precedence over systematic von Baeyer nomenclature.

Uses flexible query patterns (bond-generic) so that unsaturated derivatives (e.g. cholesterol with C=C in ring A) still match their saturated parent scaffold (cholestane). Stereochemistry is also relaxed in patterns to allow matching molecules with undefined or different stereocenters.

IUPAC: Steroid parent hydrides use retained names (androstane, pregnane, cholestane, etc.) with modification for unsaturation.

Provides: - detect_natural_product: Main detection entry point - get_non_scaffold_atoms: Identify atoms not part of matched scaffold - get_scaffold_substituents: Identify substituents attached to scaffold - is_steroid: Quick steroid check - is_alkaloid: Quick alkaloid check

orthonym.perception.natural_products.detect_natural_product(mol)#

Memoising front of:func:_detect_natural_product_impl (perf lever A7, 2026-09-13).

classify_compound_class, name_natural_product and select_parent_unified each call this on the same Mol in one pipeline pass (5,787 calls per 300 molecules, 1.2 s). The flexible scaffold queries are bond-generic and stereo-free, so the match depends on the atoms’ elements and charges (editable in place) and on connectivity (not editable on a Chem.Mol); the element/charge tuple is the memo key. The dict is copied on every call (its non_scaffold_atoms set is mutable); matched_atoms is a tuple.

orthonym.perception.natural_products.get_non_scaffold_atoms(mol, matched_atoms)#

Return atom indices NOT part of the matched scaffold.

Parameters:

  • mol – RDKit Mol object.

  • matched_atoms (tuple) – Tuple of atom indices that are part of the scaffold.

Returns:

Set of atom indices not in the scaffold.

Return type:

set

orthonym.perception.natural_products.get_scaffold_substituents(mol, matched_atoms)#

Identify substituents attached to the scaffold.

For each scaffold atom, checks its neighbors. If a neighbor is not part of the scaffold, a BFS is performed to collect the full substituent group.

Parameters:

  • mol – RDKit Mol object.

  • matched_atoms (tuple) – Tuple of atom indices that are part of the scaffold.

Returns:

List of dicts, each with – - attachment_atom: int (scaffold atom idx where substituent attaches) - substituent_atoms: list of int (all atoms in the substituent) - first_atom: int (first atom of substituent, bonded to scaffold)

Return type:

List[Dict]

orthonym.perception.natural_products.is_steroid(mol)#

Quick check: does molecule contain a steroid scaffold?

Parameters:

mol – RDKit Mol object. Returns False if mol is None.

Returns:

True if molecule contains a steroid scaffold.

Return type:

bool

orthonym.perception.natural_products.is_alkaloid(mol)#

Quick check: does molecule contain an alkaloid scaffold?

Parameters:

mol – RDKit Mol object. Returns False if mol is None.

Returns:

True if molecule contains an alkaloid scaffold.

Return type:

bool