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, or a label that says why no name was given. 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}]
                [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 (allow a few general IUPAC forms where the recommendations offer one), or cas (accepted; at present it gives the same names as pin).

Default: 'pin'

--version, -V

show program’s version number and exit

--verbose, -v

Also print the SMILES and the style. With –batch and –output, also say how many lines were named and how many failed.

Default: False

--batch, -b

Name every SMILES in this file, one per line, and print one ‘SMILES<tab>name’ line each. –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 a small table of retained trivial names is still used as a last resort at the wider tiers (the default tier declines those names); –provenance labels them systematic_verified, source trivial_retained.

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 only exceptions are names from the natural-product and metal-complex lists, the name formats absent from OPSIN’s grammar (for example inositols, phanes and thioperoxols), and PINs whose stereodescriptors OPSIN cannot read, for which the default tier compares the constitution. Otherwise it declines, with the reason code NO_VERIFIED_PIN when it built a name that is not a verified 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 11 rings (the other tiers build them up to 40 atoms and 8 rings), and adducts with a one-atom ion. 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, so the 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 and verified. ‘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) or unverified (no read-back recorded). ‘gate_outcome’ says what the final OPSIN check did, for example self_consistency_verified, suppressed, not_run or carveout:<class>. 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'

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