Python API#

The public names of the orthonym package. Everything else is internal; the counters of Orthonym (get_validation_stats, get_dispatch_stats and the others) are documented there, under orthonym.namer.

Name

What it is for

name_compound

One molecule, one name

Orthonym

All options, one engine for many molecules

Orthonym.name_tiered

The provenance row: the name, its tier, and every field of how it was checked

name_with_tree

The name and the tree of its parts

NamingResult, NameTreeNode

What name_with_tree returns

classify_limit, OrthonymLimitError

Why a structure is out of scope

is_failure_name

Tell a label from a name

Every example below is the engine’s own output.

Naming#

orthonym.name_compound(smiles, style='pin', include_confidence=False, *, enable_triviality_controller=False, enable_group_splitting=False, trivial_fallback=False, general_fallback=None, general_fallback_unverified=None, allow_aromatic_general=None, full_coverage=None, raise_on_limit=False, binding_proof='off')#

Name one molecule.

Reads a structure written as SMILES and returns its IUPAC name as a string. At the default settings a name is returned only when the strict path for the Preferred IUPAC Name built it and verified it, or when it is one of the default tier’s exceptions (the exact-match list names, the few name formats OPSIN cannot read, a PIN whose stereodescriptors OPSIN cannot read); otherwise, and where no name passes, it is a label such as 'unknown organic compound' or 'inorganic compound (not supported)'. The wider tiers (general_fallback and the options below) also return names that are not the preferred name. Use orthonym.errors.is_failure_name() to tell a label from a name, and Orthonym.name_tiered() to learn which tier a name earned.

Parameters:

  • smiles (str) – The structure, as a SMILES string.

  • style ({"pin", "general", "cas"}, default "pin") – Naming style. "pin" aims at the Preferred IUPAC Name. "general" allows a few general IUPAC forms where the recommendations offer one (for example some adduct names and axial stereodescriptors). "cas" is accepted and at present gives the same names as "pin".

  • include_confidence (bool, default False) – Return a dictionary instead of a string. Its "name" key holds the name, "handler" the part of the engine that built it, and "confidence" and "factors" a coverage score and its parts. "confidence" is None when no measurement was taken.

  • enable_triviality_controller (bool, default False) – Where the recommendations prefer a retained parent name to the systematic one, use the retained name. Each change is checked by an OPSIN round trip. The environment setting ORTHONYM_ENABLE_TRIVIALITY_CONTROLLER=1 turns this on as well.

  • enable_group_splitting (bool, default False) – When an ester or thioester group inside a larger molecule has no prefix form, write it as its parts (oxo plus ethoxy, for example) instead of giving up. Each split name must pass an OPSIN round trip. The environment setting ORTHONYM_ENABLE_GROUP_SPLITTING=1 turns this on as well.

  • trivial_fallback (bool, default False) – When no preferred name can be built, also allow a retained trivial name that is not a preferred name. A molecule whose preferred name can be built keeps it. Turns on enable_triviality_controller.

  • general_fallback (bool or None, default None) – When the strict path declines, try the general naming engine (the valid tier of the command line). Its names must pass an atom-coverage certificate and a full-InChIKey round trip. None means “off” for a call you make; the engine uses it to pass the setting on when it names parts of a molecule.

  • general_fallback_unverified (bool or None, default None) – Also switch on the best-effort tier: the last-resort producers, von Baeyer and spiro names for ring systems of up to 100 skeletal atoms and 11 rings (the other tiers build these names for ring systems of up to 40 skeletal atoms and 8 rings), and adducts with a one-atom ion. Their names still have to pass the full-InChIKey round trip. None as for general_fallback.

  • allow_aromatic_general (bool or None, default None) – Let the general engine also name aromatic and heterocyclic ring systems (the complete tier). None as for general_fallback.

  • full_coverage (bool or None, default None) – Also try the coordination-name builder for metal tetrapyrrole and corrin complexes (the full-coverage tier). It builds a name or declines. None as for general_fallback.

  • raise_on_limit (bool, default False) – Raise:class:OrthonymLimitError for a structure the engine cannot handle, instead of returning a label.

  • binding_proof ({"off", "audit", "enforce"}, default "off") – An extra check that every part of a general-engine name still maps onto the atoms it names in the final string. "audit" records the result and never changes the name; "enforce" also declines when the check fails.

Returns:

str or dict – The name, or a label that says why no name was given. A dictionary when include_confidence is true.

Raises:

  • ValueError – If RDKit cannot read the SMILES, or binding_proof is not one of the three values.

  • OrthonymLimitError – If raise_on_limit is true and the structure is out of scope.

Examples

>>> from orthonym import name_compound
>>> name_compound("CC(C)Cc1ccc(cc1)[C@@H](C)C(=O)O")
'(2R)-2-[4-(2-methylpropyl)phenyl]propanoic acid'
>>> name_compound("O=[U](=O)=O")
'inorganic compound (not supported)'
class orthonym.Orthonym(style='pin', *, _disable_grammar_validation=False, _disable_opsin_validity_gate=False, enable_triviality_controller=False, enable_group_splitting=False, trivial_fallback=False, general_fallback=False, general_fallback_unverified=False, allow_aromatic_general=False, full_coverage=False, _principal_group_override=None, _forced_parent_rank=0, _seed_excluded_dispatch_classes=frozenset({}), binding_proof='off')#

Bases: object

The naming engine, with every option.

Build one instance and name as many molecules with it as you like; the options apply to every call.:func:name_compound builds a fresh instance for each call.

Creating an instance checks that the OPSIN and centres jars are present and stops with an error if they are not (run orthonym --fetch-jars). Set ORTHONYM_ALLOW_REDUCED=1 to name without them, with no OPSIN check.

Parameters:

  • style ({"pin", "general", "cas"}, default "pin") – Naming style, as for:func:name_compound.

  • enable_triviality_controller (bool) – As for:func:name_compound. All default to False.

  • enable_group_splitting (bool) – As for:func:name_compound. All default to False.

  • trivial_fallback (bool) – As for:func:name_compound. All default to False.

  • general_fallback (bool) – The switches behind the command line’s --emit-tier. All default to False, which is the default tier. valid sets general_fallback; complete adds allow_aromatic_general; best-effort adds general_fallback_unverified; full-coverage adds full_coverage.

  • general_fallback_unverified (bool) – The switches behind the command line’s --emit-tier. All default to False, which is the default tier. valid sets general_fallback; complete adds allow_aromatic_general; best-effort adds general_fallback_unverified; full-coverage adds full_coverage.

  • allow_aromatic_general (bool) – The switches behind the command line’s --emit-tier. All default to False, which is the default tier. valid sets general_fallback; complete adds allow_aromatic_general; best-effort adds general_fallback_unverified; full-coverage adds full_coverage.

  • full_coverage (bool) – The switches behind the command line’s --emit-tier. All default to False, which is the default tier. valid sets general_fallback; complete adds allow_aromatic_general; best-effort adds general_fallback_unverified; full-coverage adds full_coverage.

  • binding_proof ({"off", "audit", "enforce"}, default "off") – As for:func:name_compound.

Notes

The parameters whose names start with an underscore are for the engine’s own use and tests; leave them at their defaults.

Examples

>>> from orthonym import Orthonym
>>> namer = Orthonym
>>> namer.name("CCO")
'ethanol'
>>> namer.name("CC(=O)O")
'acetic acid'
name_with_tree(smiles)#

Name one molecule and return the parts of the name.

Parameters:

smiles (str) – The structure, as a SMILES string.

Returns:

NamingResult – name is the same string:meth:name returns; tree is the NameTreeNode of its parts (a single coarse node when the part of the engine that built the name records no finer structure); atom_to_locant_hint maps atom indices to locants where one was recorded, else None.

Raises:

ValueError – If RDKit cannot read the SMILES.

Examples

>>> from orthonym import Orthonym
>>> Orthonym.name_with_tree("OC1CCCCC1").name
'cyclohexanol'
name(smiles, *, raise_on_limit=False)#

Name one molecule with this instance’s options.

Parameters:

  • smiles (str) – The structure, as a SMILES string.

  • raise_on_limit (bool, default False) – Raise:class:OrthonymLimitError for a structure the engine cannot handle, instead of returning a label.

Returns:

str – The name, or a label that says why no name was given (see orthonym.errors.is_failure_name()).

Raises:

  • ValueError – If RDKit cannot read the SMILES.

  • OrthonymLimitError – If raise_on_limit is true and the structure is out of scope. For a ring system the engine cannot name yet the code is UNSUPPORTED_RING_SYSTEM; when that happens inside a part of the molecule, the code reported can be the more general UNNAMEABLE.

Return type:

str

Examples

>>> from orthonym import Orthonym
>>> Orthonym.name("C/C=C/C")
'(2E)-but-2-ene'
name_with_confidence(smiles)#

Name one molecule and return a coverage score with it.

Returns:

dict – name (the name), confidence (a score from 0 to 1, or None when no measurement was taken), verification, factors (the parts of the score), handler (the part of the engine that built the name), and further keys for the atom-to-locant map and the reason for a decline (limit, abstention).

Raises:

ValueError – If RDKit cannot read the SMILES.

Return type:

dict

Examples

>>> from orthonym import Orthonym
>>> Orthonym.name_with_confidence("CCO")["name"]
'ethanol'

The provenance fields#

Orthonym.name_tiered(smiles)#

Name one molecule and say how the name was made and checked.

This is the row the command line prints with --provenance.

Parameters:

smiles (str) – The structure, as a SMILES string.

Returns:

dict –

name

The name, or a label when there is none.

tier

How the name was built: pin_verified (the strict path for the Preferred IUPAC Name built it, certified it and OPSIN read it back), pin_unverified (a name in preferred-name form that OPSIN read back, but whose preferred status is not certified: a producer outside the strict path built it or a part of it), systematic_verified (a checked systematic name that is not the preferred name, from the general engine, a table of retained names, or the strict path when the name contains a part the engine records as not the preferred form), best_effort (the last-resort producers, or a name whose own string no round trip confirmed) or abstain (no name).

is_pin

True only for a certified Preferred IUPAC Name.

source

Which part of the engine produced the name, for example pin_path, general_engine, trivial_retained or abstain.

opsin

What the OPSIN check found: verified, verified_constitution_only, unverified or n/a.

gates_passed

The checks this name passed, for example self_consistency (OPSIN read the name back to your structure) and atom_coverage.

gate_outcome

What the final OPSIN check did for this name, for example self_consistency_verified, suppressed or not_run, or carveout:<class> for a class OPSIN cannot read.

formula

The molecular formula, given when there is no name.

limit_code

The reason code when there is no name, for example UNSUPPORTED_ELEMENT, or NO_VERIFIED_PIN when the default tier built a name that is not a verified PIN (a wider tier returns it).

stereo_unexpressed

True when a stereocentre of the input is not stated in the name.

suffix_free_prefix_name

True when the name states the principal characteristic group as a prefix with no suffix.

prefix_order_fallback

True when the name cites its substituent prefixes out of the alphanumerical order because the round trip of the ordered spelling fails at the stereo layer only (a stereocentre read differently by the SMILES hand-off, not by the name); such a name is best_effort, never a PIN.

verified

opsin (OPSIN read the whole name back to the same molecule), opsin_constitution (read back with the same constitution; the stereodescriptors were not confirmed by OPSIN), identity (a name from an exact-match list: a metal-complex name found by the input’s exact InChIKey, or a natural-product parent name found by its exact structure; OPSIN cannot read these names) or unverified (no read-back recorded).

Return type:

dict

Examples

>>> from orthonym import Orthonym
>>> row = Orthonym.name_tiered("Cn1cnc2c1c(=O)n(C)c(=O)n2C")
>>> row["name"], row["tier"], row["verified"]
('1,3,7-trimethyl-3,7-dihydro-1H-purine-2,6-dione', 'pin_verified', 'opsin')

The parts of a name#

orthonym.name_with_tree(smiles, style='pin')#

Name one molecule and return the parts of the name.

A shortcut for Orthonym(style=style).name_with_tree(smiles).

Parameters:

  • smiles (str) – The structure, as a SMILES string.

  • style ({"pin", "general", "cas"}, default "pin") – Naming style, as for:func:name_compound.

Returns:

NamingResult – The name (the same string:func:name_compound returns), the tree of its parts as a:class:NameTreeNode, and a map from atom index to locant where one was recorded.

Raises:

ValueError – If RDKit cannot read the SMILES.

Examples

>>> from orthonym import name_with_tree
>>> result = name_with_tree("OC1CCCCC1")
>>> result.name
'cyclohexanol'
>>> result.tree.parent_stem
'cyclohex'
>>> result.tree.suffix
'ol'
class orthonym.NamingResult(name, tree=None, atom_to_locant_hint=None)#

Bases: NamedTuple

A name together with the tree of its parts.

Returned by:func:orthonym.name_with_tree and orthonym.Orthonym.name_with_tree(). It is a named tuple of three fields.

Variables:

  • name (str) – The name, the same string:func:orthonym.name_compound returns.

  • tree (NameTreeNode or None) – The parts of the name.

  • atom_to_locant_hint (dict of int to int or None) – Atom index to locant, where the part of the engine that built the name recorded it.

Examples

>>> from orthonym import name_with_tree
>>> name, tree, hint = name_with_tree("OC1CCCCC1")
>>> name
'cyclohexanol'
class orthonym.NameTreeNode(parent_stem, locants=(), suffix=None, prefixes=(), stereo=None, indicated_h=(), unsaturation_locants=((), ()), class_id='', multiplicative_prefix=None, parenthesization_hint=False, iupac_section_cite=None, fragment_legacy=None)#

Bases: object

One part of a name, and the parts inside it.

A name is written in the order stereodescriptors, prefixes (in alphanumerical order), parent, indicated hydrogen, unsaturation and suffix (IUPAC. A node holds those pieces for one parent; each prefix is a node of its own, so a substituent with its own substituents is a subtree. The node cannot be changed after it is made.

Variables:

  • parent_stem (str) – The parent, for example 'cyclohex'.

  • locants (tuple of int) – Locants of the suffix.

  • suffix (str or None) – The suffix, for example 'ol'.

  • prefixes (tuple of NameTreeNode) – The substituent prefixes, each a node.

  • stereo (str or None) – The stereodescriptor part, for example '(2R)'.

  • indicated_h (tuple of int) – Locants of indicated hydrogen.

  • unsaturation_locants (tuple of (tuple of int, tuple of int)) – Locants of double and of triple bonds.

  • class_id (str) – The compound class that built the node.

  • multiplicative_prefix (str or None) – A multiplying prefix such as 'di'.

  • parenthesization_hint (bool) – True when the prefix must be written in enclosing marks.

  • iupac_section_cite (str or None) – The section of the recommendations the node follows, for example ''.

  • fragment_legacy (object or None) – An older representation of the same part, kept for the engine’s own use.

Examples

>>> from orthonym import name_with_tree
>>> tree = name_with_tree("OC1CCCCC1").tree
>>> tree.parent_stem, tree.suffix
('cyclohex', 'ol')

Declines#

orthonym.classify_limit(smiles)#

Say whether a structure is out of scope, without raising.

A wildcard atom (*) is refused at once. Any other structure is named with the default settings; if that gives a label instead of a name, the reason is returned.

Parameters:

smiles (str) – The structure, as a SMILES string.

Returns:

OrthonymLimitError or None – The reason, with its code (for example UNSUPPORTED_ELEMENT, WILDCARD_ATOMS, or NO_VERIFIED_PIN when the default settings built a name that is not a verified preferred IUPAC name) and message. None when the structure gets a name, and also when RDKit cannot read the SMILES at all (that is a reading error, not a scope limit).

Return type:

OrthonymLimitError | None

Examples

>>> from orthonym import classify_limit
>>> classify_limit("O=[U](=O)=O").code
'UNSUPPORTED_ELEMENT'
>>> classify_limit("CC*").code
'WILDCARD_ATOMS'
>>> classify_limit("CCO") is None
True
exception orthonym.OrthonymLimitError(code, message, design_note_ref=None, smiles=None)#

Bases: Exception

The reason a structure is out of scope.

Returned by:func:orthonym.classify_limit, and raised when you ask for it with raise_on_limit=True. It tells “cannot handle this structure” apart from a name.

Variables:

  • code (str) – The reason code: WILDCARD_ATOMS, UNSUPPORTED_ELEMENT, ISOLATED_ATOM, STRUCTURE_TOO_LARGE, UNSUPPORTED_RING_SYSTEM, UNNAMEABLE or NO_VERIFIED_PIN (the default tier built a name but not a verified preferred IUPAC name; a wider tier returns it).

  • message (str) – The label the plain call returns in place of a name.

  • design_note_ref (str or None) – A reference to the design note the code follows.

  • smiles (str or None) – The input, when known.

Examples

>>> from orthonym import Orthonym, OrthonymLimitError
>>> try:
... Orthonym.name("O=[U](=O)=O", raise_on_limit=True)
... except OrthonymLimitError as err:
... print(err.code, "|", err.message)
UNSUPPORTED_ELEMENT | inorganic compound (not supported)
orthonym.errors.is_failure_name(name)#

Tell a label from a name.

When the engine cannot name a structure, the plain call returns a label in place of a name, such as 'inorganic compound (not supported)' or 'unknown organic compound'. This function is true for those labels and for an empty result, and false for a real name.

Parameters:

name (str or None) – What a naming call returned.

Returns:

bool – True when name is empty or a label (it contains unknown or (not supported)).

Return type:

bool

Examples

>>> from orthonym import name_compound
>>> from orthonym.errors import is_failure_name
>>> is_failure_name(name_compound("O=[U](=O)=O"))
True
>>> is_failure_name(name_compound("CCO"))
False

Version#

orthonym.__version__ is the installed version, a string such as '1.0.2'.