Command-line options#

The program’s own help text, read from its option parser when the site is built. The same options in plain words, grouped by what they are for, are on Command line.

Orthonym: IUPAC names for chemical structures. Give a SMILES string and get its IUPAC name, checked by reading it back with OPSIN. A structure that gets no name has an empty name and a reason on the error stream (–on-failure). The few names OPSIN cannot read in full are marked by –provenance.

usage: orthonym [-h] [--style {pin,general,cas}] [--version] [--verbose]
                [--batch BATCH] [--output OUTPUT] [--confidence]
                [--validation-stats] [--dispatch-stats] [--dump-tree]
                [--format {text,json}] [--enable-triviality-controller]
                [--trivial]
                [--emit-tier {pin,valid,complete,best-effort,full-coverage}]
                [--provenance] [--engine-only] [--fetch-jars]
                [--binding-proof {off,audit,enforce}]
                [--on-failure {empty,label,raise}]
                [smiles]

Positional Arguments#

smiles: The structure, as a SMILES string (in quotes).

Named Arguments#

--style

Possible choices: pin, general, cas

Naming style: pin (aim at the Preferred IUPAC Name; the default), general or cas. general allows general IUPAC forms where the recommendations offer one, for example functional class names (‘dimethyl sulfoxide’, ‘methyl isocyanate’), hydrate names (‘oxalic acid dihydrate’) and the axial descriptors Ra and Sa. The default tier’s PIN-only rule applies to pin only, so with general or cas a name that pin declines with NO_VERIFIED_PIN is returned. cas is accepted and at present gives the names of general, except that hydrate names and axial descriptors keep their pin form.

Default: 'pin'

--version, -V

show program’s version number and exit

--verbose, -v

Also print the SMILES and the style. With –batch, also say how many lines were read, how many failed and how many got no name.

Default: False

--batch, -b

Name every SMILES in this file, one per line, and print one ‘SMILES<tab>name’ line each; the name is empty for a line that gets no name (–on-failure). –emit-tier and –provenance do not apply to batch runs yet.

--output, -o

With –batch: write the lines to this file instead of the screen.

--confidence

Print the name with a coverage score, the part of the engine that built it, and the parts of the score.

Default: False

--validation-stats

After the name, print on the error stream how often the OPSIN grammar pre-check passed or repaired a candidate name.

Default: False

--dispatch-stats

After the name, print on the error stream which compound-class routes the engine took.

Default: False

--dump-tree

Print the parts of the name as a tree instead of the name.

Default: False

--format

Possible choices: text, json

Layout for –dump-tree: text (an indented tree; the default) or json.

Default: 'text'

--trivial

When no preferred name can be built, also allow a retained trivial name that is not a preferred name. A preferred name that can be built is never replaced (glycerol stays propane-1,2,3-triol). Without this option, two kinds of retained trivial name are still used at the wider tiers, and the default tier declines them: names from a small last-resort table, and the trivial natural-product names of molecules whose preferred bridged fused name the engine does not build yet (diamorphine). –provenance labels both systematic_verified, source trivial_retained. A natural-product name built on a parent, such as ‘(9R,13S,14S)-3-methoxy-17-methylmorphinan’, is not a trivial name, and –trivial does not return it at the default tier.

Default: False

--emit-tier

Possible choices: pin, valid, complete, best-effort, full-coverage

Which names to return. pin (the default): a name only when the pipeline can build the preferred IUPAC name (PIN), that is when the strict PIN path built the name and verified it (tier pin_verified). The exceptions are names from the natural-product and metal-complex lists, the name formats absent from OPSIN’s grammar (inositols; phanes, checked by building their structure), PIN spellings that OPSIN reads back through a twin spelling of the same structure (ethan(2H)ol, diphenyliodanuide, methane-SO-thioperoxol) or through their acids (dianhydrides), PINs whose stereodescriptors OPSIN cannot read, for which the default tier compares the constitution, and, with –trivial, a retained trivial name. Otherwise it declines, with the reason code NO_VERIFIED_PIN when it built a name that is not a verified PIN. The rule applies to the default –style pin. valid: also names from the general engine. complete: also general names for aromatic and heterocyclic ring systems. best-effort: also the last-resort producers, von Baeyer and spiro names for ring systems of up to 100 skeletal atoms and 15 rings (the other tiers build them up to 40 atoms and 8 rings), and adducts with a one-atom ion, and, for a molecule that has no other name, the name the default tier ships although OPSIN cannot read its stereodescriptors, with the label of the default tier (pin_unverified). full-coverage: also the coordination-name builder for metal tetrapyrrole and corrin complexes, which builds a name or declines. The wider tiers also return the names the default tier declines, each labelled with its tier; there every name must pass a full-InChIKey OPSIN round trip, except a name from the natural-product and metal-complex lists, a twin-checked name for which the engine has no other spelling (a halogen -uide anion, the anion of a thioperoxol, an organometallic name with halido ligands) and the best-effort name described above, so the other name formats absent from OPSIN’s grammar are declined there. –provenance shows each name’s tier.

Default: 'pin'

--provenance

Print a JSON row instead of the bare name, with the keys name, tier, is_pin, source, opsin, gates_passed, gate_outcome, formula, limit_code, stereo_unexpressed, suffix_free_prefix_name, prefix_order_fallback, verified, spelling_failures and producer. ‘verified’ is opsin (OPSIN read the whole name back to the same molecule), opsin_constitution (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), opsin_split (read back to the input without its dative bonds, which the drawing as given has no key for), opsin_twin (a PIN spelling OPSIN has no grammar for, read back through a twin spelling of the same structure), opsin_acids (a poly-anhydride, read through its acids) or unverified (no read-back recorded). ‘gate_outcome’ says what the final OPSIN check did, for example self_consistency_verified, suppressed, not_run, carveout:<class>, twin_verified:<rules> or acid_split_verified:<rule>. ‘spelling_failures’ lists the spelling rules of the PIN (rule id and detail) that a name in PIN form breaks, and the rule of a recorded non-PIN part that lowered the name; such a name is not labelled pin_verified, and pin declines it. One SMILES at a time; not with –batch.

Default: False

--engine-only

For inspection only: skip the strict path and print, as JSON, the general engine’s own name (checked for atom coverage, not by OPSIN) or that it declined. Never a preferred name; do not use it as a name.

Default: False

--fetch-jars

Download the OPSIN and centres jars if they are missing, check each against the SHA-256 checksum recorded in Orthonym, print where they are, and stop (exit status 1 on failure). A jar given by ORTHONYM_OPSIN_JAR or ORTHONYM_CENTRES_JAR is used as given, without the checksum check.

Default: False

--binding-proof

Possible choices: off, audit, enforce

An extra check that every part of a general-engine name still maps onto its atoms in the final name: off (the default), audit (record the result; the name never changes), or enforce (also decline when the check fails). Works for one SMILES and for –batch.

Default: 'off'

--on-failure

Possible choices: empty, label, raise

What to give for a structure that gets no name. empty (the default): an empty name, and on the error stream a line with the SMILES, the limit code and the reason, ‘<SMILES><tab><CODE>: <reason>’. label: the reason as the name, ‘unknown organic compound’ for example. raise: stop with an error (status 1; with –batch the line gets ERROR: and the run ends with status 1). It applies to a name, –confidence and –batch; –provenance, –dump-tree and –engine-only report the structure as it is. With –batch –verbose the count of lines without a name is printed.

Default: 'empty'

Retained parent names#

--enable-triviality-controller

Use a retained parent name (benzene, phenol, aniline, benzoic acid and others) where the IUPAC 2013 recommendations prefer it to the systematic one (P-15.1.8). Every change is checked by an OPSIN round trip. Off by default; ORTHONYM_ENABLE_TRIVIALITY_CONTROLLER=1 turns it on too.

Default: False