Pubchem Structure Lookup By Name

pubchem-structure-lookup-by-name

Summary

Automatically retrieve chemical structure data (SMILES, InChI, molecular formula, CID) from PubChem for metadata entries lacking structural information by performing name-based searches. This skill bridges gaps in incomplete chemical metadata tables during preprocessing for mass spectrometry or natural product workflows.

When to use

Your metadata table contains compound names but lacks structure information (SMILES, InChI, molecular formula, or PubChem CID). This is particularly relevant when preparing entries for querying natural product or drug databases that require standardized structural identifiers, or when enriching heterogeneous datasets compiled from multiple sources (e.g., combining LOTUS, DrugBank, and user-supplied compounds).

When NOT to use

• Compound names are ambiguous, non-standard, or proprietary (e.g., internal lab codes without chemical nomenclature); PubChem Name search may return incorrect or no results.
• Structure information is already provided in the metadata table; this skill is redundant and will waste API quota.
• High-throughput structure resolution is needed for >100,000 compounds; consider batch APIs or local chemical libraries to avoid rate limiting.

Inputs

• Metadata table (CSV, TSV, or spreadsheet) with compound names and optional partial structure information
• List of compound names lacking structure data

Outputs

• Enriched metadata table with appended structure columns (SMILES, InChI, molecular formula, PubChem CID)
• Mapping of original compound names to PubChem identifiers

How to apply

Load the metadata table and identify rows where structure fields are empty or absent. For each compound with missing structure, submit the compound name as a query to the PubChem API (or web interface) using the Name search endpoint. Extract the returned structure data fields—SMILES string, InChI notation, molecular formula, and PubChem CID—from the top result (or manually review if multiple matches exist). Merge the retrieved fields back into the original metadata table by appending new columns while preserving all existing columns and row order. Validate that newly populated structure fields conform to expected formats (e.g., SMILES syntax, InChI prefix) before saving the enriched table.

Related tools

• PubChem (Primary query service for compound name-to-structure resolution; returns SMILES, InChI, molecular formula, and CID via Name search API)
• jobs.py (Prefect job definition and control file; set local database flags (e.g., PubChem query parameters) and enable/disable external queries) — https://github.com/corinnabrungs/msn_tree_library
• metadata_cleanup_prefect.py (Orchestrates metadata enrichment workflow as a Prefect 2 flow; manages task sequencing including structure lookup) — https://github.com/corinnabrungs/msn_tree_library
• prepare_wikidata_lotus_prefect.py (Optionally updates LOTUS natural product database before or alongside structure lookups to ensure matched compounds are checked against curated reference data) — https://github.com/corinnabrungs/msn_tree_library

Evaluation signals

• All originally empty structure fields are now populated with non-empty SMILES, InChI, and CID values; no row should have structure data unless a successful PubChem lookup occurred.
• SMILES strings pass chemical validity checks (e.g., balanced brackets, valid atomic symbols); InChI strings begin with 'InChI=' prefix.
• PubChem CID values are numeric and consistent with PubChem's public record identifiers (resolvable via pubchem.ncbi.nlm.nih.gov/compound/{CID}).
• Molecular formula matches the structure (SMILES/InChI can be converted to formula and compared).
• Enriched table row count and original columns are preserved; no rows were lost or duplicated during merge.

Limitations

• PubChem Name search may return multiple hits for ambiguous compound names; automated selection of the top result risks retrieving the wrong isomer or salt form. Manual review or disambiguation rules are recommended for high-confidence workflows.
• Compounds not indexed in PubChem (e.g., newly synthesized or proprietary molecules, rare natural products) will fail to retrieve structure; these entries remain unfilled and require manual curation or alternative databases.
• Rate limiting on PubChem's public API may throttle large-batch queries; consider batch API access or local structure libraries for high-throughput enrichment.
• Compound name variations (e.g., trade names, systematic IUPAC names, abbreviations, partial names) may yield different PubChem records; standardization of input names improves recall.

Evidence

• [readme] If no structure information is provided, it is queried from PubChem by Name search: "If no structure information is provided, it is queried from PubChem by Name search"
• [other] Extract structure data (SMILES, InChI, molecular formula, and PubChem CID) from the returned results.: "Extract structure data (SMILES, InChI, molecular formula, and PubChem CID) from the returned results"
• [other] Merge retrieved structure information back into the metadata table, preserving original columns and appending new structure fields.: "Merge retrieved structure information back into the metadata table, preserving original columns and appending new structure fields"
• [other] For each compound with missing structure, submit a PubChem Name search query via the PubChem API or web interface.: "For each compound with missing structure, submit a PubChem Name search query via the PubChem API or web interface"
• [readme] Please use the [template] for your metadata for having same column names and minimum needed information for the query: "Please use the [template] for your metadata for having same column names and minimum needed information for the query"