Compound name lookup

What it does. Two calls per compound against the Metabolomics Workbench REST API: /refmet/match/<name> for the standardized name, formula and exact mass, then /refmet/refmet_id/<id> for the InChIKey, PubChem CID and SMILES. Names RefMet does not have fall through to the PubChem PUG REST API (/pug/compound/name/<name>/property/..., then /pug/compound/inchikey/<key>/property/...), and names PubChem cannot match go to OPSIN at EBI (/opsin/ws/<name>.json) to be parsed into a structure. Nothing is sent anywhere else and nothing is stored.

Always check the flags. RefMet resolves a name to its best match, which is not always the right molecule. A CHECK flag means the returned formula does not match what you supplied, or nothing was found in either database. Known failure modes: menaquinone resolves to menadione (a different compound entirely), and AICAR resolves to the dephosphorylated riboside.

Tier 1, RefMet — trusted. Anything RefMet resolves is kept exactly as returned and never second-guessed by a later tier. RefMet is a metabolite nomenclature database, not a general chemical registry, so many xenobiotics are absent from it completely — not findable by name, exact name, InChIKey, InChIKey skeleton, PubChem CID or formula, all of which were checked against the live API for 1,1,1,3,3,3-Hexafluoro-2-(pyridin-2-ylamino)propan-2-ol. Every route comes back empty, so there is no RefMet ID to find and no setting here can conjure one. This is not a blanket exclusion of odd chemistry — RefMet does hold PFOA (RM0033243), fluorouracil (RM0109153), trifluoroacetic acid (RM0188146) and sitagliptin (RM0052706).

Tier 2, PubChem by name. Since ClassyFire keys off the InChIKey rather than the RefMet ID, answering from PubChem still gets you a usable row. But a PubChem row is weaker evidence than a RefMet row and the source column exists so you never have to guess which you are looking at. PubChem's name matching is looser than RefMet's and will resolve some strings to a plausible but wrong record with no complaint.

Tier 3, OPSIN then PubChem by InChIKey. PubChem's name endpoint queries a synonym dictionary, so it only finds compounds somebody registered names for. Auto-generated structure records have no synonyms at all and can never be found by name, however you spell them — which matters because that is exactly where exposure and xenobiotic lists live. Worked example: (2-Chloroethenyl)bis(2,2,3,3-tetrafluorocyclobutyl)silane is PubChem CID 71330661, but that CID returns 404 No synonyms found, and the 2-Chloroethenyl-bis(...)silane shown on the PubChem web page is a generated display name rather than an indexed synonym. Both spellings 404 identically on /name/ — the punctuation is a red herring.

So for a systematic name the fix is to parse it rather than look it up. OPSIN turns the name into a structure with no database entry required — both spellings above parse to the same key, RMXLHIADRFSFBV-UHFFFAOYSA-N — and PubChem's InChIKey endpoint then resolves that to CID 71330661. Deliberately not used here: PubChem's name_type=word. It does find this compound, but it is a bag-of-words search that will confidently return unrelated compounds sharing a few tokens. OPSIN either parses a name correctly or fails outright, which is what a QC tool wants. The trade-off is that OPSIN only handles systematic names — trade names and trivial names still fall through to not found.

This tier sends the compound name to EBI (www.ebi.ac.uk/opsin/ws/), a third party the rest of this tool never contacts. If your list is proprietary or pre-publication, untick parse systematic names (OPSIN).

Reading the fallback flags. The only thing corroborating a tier 2 or tier 3 row is the formula or mass you pasted alongside the name:

• PubChem only / PubChem via OPSIN — your pasted formula or mass agrees.
• … — 1H — agrees to within one hydrogen (protonation convention, as below).
• … — unverified — you supplied nothing to check it against. The name resolved, and that is all anyone knows. Verify these by hand before using them.
• OPSIN only, no PubChem record — the name parsed to a valid structure that PubChem does not hold. You get a formula and an InChIKey but no mass, because no database has one for it.

No mass is ever computed here. Every mass shown came from RefMet or PubChem, so it is always an independent value to check your own against. Deriving a mass from a formula that was itself parsed out of the name you pasted would be checking the input against itself and would make a fallback row look better-corroborated than it is — so the mass column is simply left empty when no database supplies one.

Fallback rows leave RefMet ID empty and are not CID-verified: the CID came from PubChem, so asking PubChem to confirm it would only be asking one source to agree with itself. Untick both fallbacks to get RefMet-only behaviour, where all of these come back as CHECK — not found.

Extra columns. Paste tab-separated columns straight from Excel. If the first row looks like a header it is used to find the name, formula and mass columns by their names — so the IROA sheet (Molecule Name, Molecular Formula, Neutral Mass, RT (min)) can be pasted whole and RT is simply ignored. Without a header row the columns are read positionally as name, formula, mass. A blue line under the buttons says which mapping was used — check it before trusting the results.

Columns are split on TAB only, never commas. Chemical names contain commas (2,3-dihydroxybenzoate, cytidine 2',3'-cyclic phosphate) and splitting on them would truncate the name to 2 and silently look up the wrong compound. If you only have a comma-separated list, paste it into Excel first and copy the column back out.

Formula and mass are checked independently. Formula catches a wrong molecule with a different composition. Mass catches one RefMet returned with no formula, and quantifies how far off it is. The mass tolerance defaults to 10 mDa and can be switched to ppm. The Δ mDa column is signed, RefMet minus yours, so a systematic offset is visible at a glance.

PubChem CID verification. RefMet's name-to-compound link is occasionally right about the molecule but wrong about which PubChem record it points at — specifically, it can land on the wrong stereoisomer. Aflatoxin G1 is the worked example: RefMet returns CID 15939117, the (7aR-cis) enantiomer, where the natural product is CID 2724361. Identical formula, identical exact mass, identical InChIKey skeleton block — so the formula and mass checks above cannot see it. With verify CIDs against PubChem ticked, each CID is checked by asking PubChem for that record's synonyms and confirming RefMet's own standardized name is among them. Failures are flagged CHECK — CID mismatch and the name-resolved CID is shown in its own column; RefMet's value is never silently overwritten. Leaving this ticked makes every run slower — untick it for faster results. Each compound costs one extra PubChem request (two only when the check fails), and they are spaced out to stay inside PubChem's 5-per-second ceiling, so a few hundred compounds take roughly half as long again with it off.

Why the check uses RefMet's name, not yours. Comparing your pasted name straight to a PubChem name lookup would flag correct answers. Querying citrate gives the RefMet name Citric acid and CID 311, which is right, but PubChem's own lookup for citrate returns 31348, the anion. Checking RefMet's standardized name against the synonyms of the CID it gave us tests the link RefMet actually made, and leaves the conjugate-base handling alone.

Protonation states differ. Zwitterions with a quaternary nitrogen (thiamine pyrophosphate, NAADP, nicotinamide hypoxanthine dinucleotide) often come back one hydrogen off from a neutral-form reference list. Same molecule, different convention — flagged as 1H rather than an error.

Next step — compound classes. Hit Copy InChIKeys, then paste them into the ClassyFire batch query at cfb.fiehnlab.ucdavis.edu. It returns Kingdom / Superclass / Class / Subclass per InChIKey as a CSV you can join back onto these results on the InChIKey column. Only keys that pass the flag checks above are worth submitting — a wrong compound will still classify cleanly and give you a confidently wrong class. Copy InChIKeys includes PubChem-sourced keys, since classifying them is the whole point of the fallback; filter the CSV on source first if you want RefMet-only classes.