orthonym.rules.natural_products#

Note

Internal API. Names and behaviour may change between releases.

Natural product naming rules.

Provides the naming function that bridges perception (scaffold detection) and data (derivative lookup) to return trivial/retained names for natural product molecules.

Algorithm: 1. Exact derivative lookup (O(1) dict lookup by canonical SMILES) 2. Scaffold substructure match via perception module 3. Return scaffold name for bare scaffolds 4. For decorated scaffolds (steroid class): enumerate -OH, =O, C=C, esters

and assemble a systematic name using the scaffold stem

  1. Return None for non-natural-product molecules

Decoration enumeration (steroids): - Hydroxyl groups -> prefix “hydroxy” with locant - Ketone groups -> suffix “-one” with locant - Double bonds -> suffix “-ene” with locant - Triple bonds -> suffix “-yne” with locant - Ester groups -> functional class format: parent-yl acylate (IUPAC

orthonym.rules.natural_products.detect_np_modifications(mol, scaffold_info, numbering)#

Detect nor-, homo-, seco- modifications vs matched NP scaffold.

Compares the molecule’s structure against the matched scaffold to identify structural modifications per IUPAC steroid nomenclature rules 3S-7/3S-8.

Current detection capabilities: - nor-: Missing angular methyls (C-18, C-19) in steroid scaffolds.

Detected by comparing the matched scaffold’s numbering against the reference expectation for a complete steroid.

  • homo-: Placeholder for ring expansion detection (future).

  • seco-: Placeholder for ring-opening detection (future).

Parameters:

  • mol – RDKit Mol object.

  • scaffold_info (Dict) – Dict from detect_natural_product with keys: scaffold_name, scaffold_stem, scaffold_class, scaffold_smiles, matched_atoms, non_scaffold_atoms.

  • numbering (Dict[int, int]) – Target atom index -> IUPAC locant mapping from _build_target_to_iupac.

Returns:

List of modification dicts, each with keys – - prefix: str (‘nor’, ‘homo’, or ‘seco’)

  • locants: List[int] (IUPAC locant numbers)

  • ring_letter: Optional[str] (for homo-, e.g., ‘D’)

Empty list if no modifications detected.

Return type:

List[Dict]

orthonym.rules.natural_products.format_np_modification_prefix(modifications)#

Format modification prefixes per IUPAC nomenclature.

IUPAC steroid nomenclature rules 3S-7, 3S-8: - nor-: ‘{locant}-nor’ or ‘{loc1},{loc2}-dinor’ etc. - homo-: ‘{ring_letter}-homo’ or ‘{locant}-homo’ - seco-: ‘{loc1},{loc2}-seco’

Multiple modifications are sorted alphabetically by prefix name (homo < nor < seco) and concatenated with hyphens.

Parameters:

modifications (List[Dict]) – List of modification dicts from detect_np_modifications.

Returns:

Combined prefix string (e.g., ‘19-nor’, ‘D-homo-19-nor-9,10-seco’) or empty string if no modifications.

Return type:

str

orthonym.rules.natural_products.name_natural_product(mol)#

Name a molecule using natural product recognition.

Tries exact derivative lookup first, then scaffold substructure matching. For steroids with decorations, enumerates functional groups. Returns None for molecules that are not recognized natural products.

Parameters:

mol – RDKit Mol object.

Returns:

Trivial/retained name if the molecule is a recognized natural product, otherwise None.

Return type:

str | None

orthonym.rules.natural_products.name_natural_product_with_substituents(mol, scaffold_info, modification_prefix='')#

Name a natural product with decorations on the scaffold.

For steroids: enumerates hydroxyl, ketone, unsaturation, and ester decorations, assembles a systematic name like “3-hydroxycholest-4-en-17-one” or functional class format “3-oxoandrost-4-en-17-yl acetate” for esters.

Returns None (the systematic pipeline names the molecule) when a decoration cannot be cited: no numbering map for the scaffold, or a decoration kind the chosen assembler does not take.

Parameters:

  • mol – RDKit Mol object.

  • scaffold_info (Dict) – Dict from detect_natural_product with keys: - scaffold_name: str - scaffold_stem: str - scaffold_class: str - scaffold_smiles: str - matched_atoms: tuple - non_scaffold_atoms: set

  • modification_prefix (str) – NP modification prefix string (e.g., ‘19-nor’) to insert before the scaffold stem. Empty string if no modifications.

Returns:

Name string for the natural product.

Return type:

str