Chemical type classification and annotation

chemical-type-classification-and-annotation

License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->

Summary

Classify and annotate query chemicals against a user-defined or restricted library of compound type categories using structural matching and categorical database lookups. This skill identifies best-matching compound types for GC-MS detected chemicals and enriches them with cross-database metadata (PubChem, LOTUS, KEGG, FEMA, FDA/SPL).

When to use

Apply this skill after identifying query chemicals from GC-MS data (via Match.Factor filtering or manual selection) and you need to: (1) assign each query chemical to a best-matching type category within a restricted compound library, or (2) annotate query chemicals with categorical attributes (reactive groups, natural product occurrence, bioactivity, flavor/odor designation, or FDA/SPL presence) to enable downstream filtering or prioritization.

When NOT to use

• Query chemicals are already structurally classified or annotated within your own internal taxonomy and re-annotation against external categories is not required.
• Input data lacks standardized chemical names; categorate() relies on exact or fuzzy name matching to public databases via webchem and will fail or produce spurious matches on malformed, proprietary, or non-standard chemical identifiers.
• The chemical library is empty, malformed (missing column names or type groupings), or incompatible with wide-format input_format='wide' specification.

Inputs

• vector of query chemical names (character vector, e.g., c('Ethyl hexanoate', 'Methyl salicylate', 'Octanal', 'Undecane'))
• chemical library data.frame (wide format: columns = type sets, rows = compound identifiers or chemical names)
• optional: pre-filtered GC-MS compound list (Compound.Name column with Match.Factor >= user-defined threshold, e.g., 70–80)

Outputs

• categorate() best-match table (data.frame): rows = query chemicals, columns = type categories and compound identifiers (CMP1, CMP2, etc.) or 'No' for unmatched
• enriched annotation data.frame: includes categorical attributes (reactive groups, LOTUS membership, KEGG bioactivity, FEMA flavor code, FDA/SPL status) for each query chemical
• subset vectors (character): output from exactoThese() for downstream m/z extraction via mzExacto()

How to apply

Pass a vector of query chemical names (e.g., c('Linalool', 'Methyl Salicylate', 'Limonene')) and a structured chemical library (as an R data.frame with compounds grouped by type or category) to the categorate() function with input_format='wide'. The function accesses ChemmineR and fmcsR to perform structural matching via flexible maximum common substructure (FMCS) scoring, returning a best-match table that identifies the highest-scoring structural match (typically Match.Factor >0.95) within each type set for each query chemical. For each chemical, categorate() queries PubChem (reactive groups), LOTUS (natural products), KEGG (bioactivities), FEMA (flavor/odor), and FDA/SPL (regulatory status) via webchem, producing a data.frame where rows are query chemicals and columns represent categorical membership or best-matching type identifier (e.g., 'CMP1', 'CMP2', 'GroupA', or 'No' for no match). Use exactoThese() downstream to subset the categorated results by Database, FMCS structural properties (MW, rings, groups, atoms, charges), or Library group assignment.

Related tools

• ChemmineR (Performs cheminformatics analysis and structural comparisons; core engine for FMCS matching in categorate()) — https://www.bioconductor.org/packages/release/bioc/html/ChemmineR.html
• fmcsR (Computes flexible maximum common substructure (FMCS) similarity scores between query and library chemicals; returns Match.Factor-like scores for type assignment) — https://bioconductor.org/packages/release/bioc/html/fmcsR.html
• webchem (Queries PubChem, LOTUS, KEGG, FEMA, and FDA/SPL databases to retrieve categorical metadata (reactive groups, natural products, bioactivities, flavor, regulatory status) for annotating query chemicals) — https://cran.r-project.org/web/packages/webchem/index.html
• R (Execution environment and host language for categorate(), exactoThese(), and data manipulation)
• uafR (Package containing categorate() and exactoThese() functions for chemical classification and downstream subsetting workflows) — https://github.com/castratton/uafR

Examples

query_chemicals = c("Linalool", "Methyl Salicylate", "Limonene"); GroupA = c("Guaiacol", "Tridecane", "Ethyl heptanoate"); GroupB = c("2-Aminothiazole", "Aspirin", "Octanoic acid"); chem_library = data.frame(cbind(GroupA, GroupB)); query_categorated = categorate(query_chemicals, chem_library, input_format = "wide")

Evaluation signals

• Best-match table contains exactly one row per query chemical and at most one assigned type (CMP identifier, GroupA/B label, or 'No') per type set; no duplicates or NA values in the best-match column.
• Each matched compound has a structural Match.Factor or FMCS score >0.95 (or user-specified threshold); verify scores in the output data.frame or by inspecting categorate() intermediate outputs.
• Cross-database annotation columns (Database, reactive_groups, LOTUS, KEGG, FEMA, FDA_SPL) are populated (non-empty) for chemicals successfully queried to external databases; missing annotations align with known database coverage gaps (e.g., very novel or highly proprietary compounds may return 'NA' or 'Unknown').
• Downstream exactoThese() subsetting on categorate() output (e.g., subsetBy='Database', subsetArgs='FEMA') returns a non-empty vector of chemical names matching the requested criteria; vector length is consistent with library composition.
• mzExacto() successfully extracts m/z peaks and retention times for chemicals returned by exactoThese(query_categorated, ...) with no errors or missing values in the input_exacto output table.

Limitations

• categorate() relies on exact or fuzzy name matching via webchem; synonym variants, abbreviations, or IUPAC/common name discrepancies may cause database query failures, leading to missing or incorrect annotations.
• Structural matching (FMCS) assumes input chemical library compounds have associated SMILES or structure formats; if library compounds lack chemical structure data, fmcsR cannot compute similarity scores and categorate() will default to 'No' match.
• Match.Factor and FMCS thresholds (>0.95) are heuristic; chemicals with borderline similarity (0.85–0.95) may be excluded from classification even if chemically related. Users should validate threshold choice against domain knowledge.
• External database queries (PubChem, LOTUS, KEGG, FEMA, FDA/SPL) are network-dependent and subject to rate limits, API availability, and version drift; outdated or temporarily unavailable databases will produce 'NA' or stale annotation values.
• categorate() output is deterministic only if chemical library and query list are stable; adding or reordering library compounds or query chemicals will alter best-match assignments due to FMCS pairwise scoring.

Evidence

• [other] categorate() function correctly match chemical compounds to their best-matching compound type categories: "The categorate() function, when applied under structural-matching conditions restricted to 4 chemical type sets, produces a best-match table that correctly identifies compound classifications (e.g.,"
• [methods] categorate() accesses categorical data from multiple databases: "categorate() is an overpowered function that accesses a broad array of categorical data for searched chemicals."
• [methods] categorate() uses ChemmineR, fmcsR, and webchem for structural matching: "Call categorate() on the query chemicals, passing the restricted library to access structural match data via ChemmineR, fmcsR, and webchem."
• [readme] exactoThese() enables subsetting of categorate() output by database, FMCS properties, or library group: "these_chems = exactoThese(query_categorated, subsetBy = "Database", subsetArgs = "FEMA") these_chems = exactoThese(query_categorated, subsetBy = "FMCS", subsetArgs = "MW", subsetArgs2 = "Greater"
• [methods] External databases queried include PubChem, LOTUS, KEGG, FEMA, FDA/SPL: "Reactive Groups from PubChem, natural products occurrences from LOTUS, bioactivites and risk categories from the Kyoto"
• [readme] categorate() with wide-format input: "query_categorated = categorate(query_chemicals, chem_library, input_format = "wide")"