Compound library construction and curation

compound-library-construction-and-curation

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

Summary

Assemble and organize chemical reference libraries (e.g., GroupA, GroupB, or restricted type sets) as data structures for downstream structural matching and categorical enrichment. This skill ensures that query chemicals can be accurately matched against well-curated compound sets using cheminformatics tools.

When to use

When you have a set of query chemicals (e.g., ethyl hexanoate, methyl salicylate, octanal, undecane) and need to evaluate them against reference compound categories, or when you want to restrict structural matching to specific compound type sets (e.g., Type A–E chemical sets) rather than uncontrolled libraries. Use this skill before calling categorate() or mzExacto() to ensure the reference library is correctly formatted and semantically organized.

When NOT to use

• If your reference library is already pre-matched and indexed externally (e.g., linked to a public database like PubChem or KEGG without need for local curation).
• If you are only interested in mass spectrometry peak matching without structural classification; use mzExacto() directly on unsorted input instead.
• If your query chemicals are already fully annotated with database identifiers (e.g., CAS numbers, InChI keys) and do not require structural similarity matching.

Inputs

• list of query chemical names (character vector or from CSV Compound.Name column)
• reference compound groups (named character vectors, e.g., GroupA, GroupB)
• compound type sets (Type A–E chemical sets or equivalent restricted library)
• input data frame with columns: Compound.Name, Match.Factor (optional for pre-filtering)

Outputs

• structured reference library data frame (wide format with group/type columns)
• best-match table showing query chemical name, matched type/group, and compound identifier (CMP1, CMP2, etc., or 'No' for no match)
• structural match scores (>0.95 threshold for reliable matches)
• curated query_chemicals vector ready for downstream analysis via exactoThese() or mzExacto()

How to apply

Structure your reference compounds into named groups (e.g., GroupA, GroupB) and combine them into a data frame with input_format = 'wide' for use with the categorate() function. Load both the query chemical list and the restricted type library as R data structures. Ensure library columns correspond to chemical type categories and contain verified compound identifiers or names. Pass the curated library to categorate() along with your query chemicals; the function will then perform structural matching via ChemmineR and fmcsR to return a best-match table. Verify that match scores exceed 0.95 for reliable classifications and that output identifiers (e.g., 'CMP1', 'CMP2', 'No match') are consistent with your library schema.

Related tools

• ChemmineR (Provides structural matching and cheminformatics data access for compound classification within the library) — https://www.bioconductor.org/packages/release/bioc/html/ChemmineR.html
• fmcsR (Computes flexible maximum common substructure (FMCS) matches to calculate structural similarity scores between query and library compounds) — https://bioconductor.org/packages/release/bioc/html/fmcsR.html
• webchem (Retrieves and enriches chemical metadata (names, properties, database identifiers) for library compounds) — https://cran.r-project.org/web/packages/webchem/index.html
• R (Data frame construction, library organization, and automation of workflow)

Examples

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

Evaluation signals

• Best-match table returns compound identifiers (CMP1, CMP2, etc.) for all query chemicals; 'No' entries indicate compounds without matches above the 0.95 score threshold.
• Structural match scores for high-confidence matches (e.g., ethyl hexanoate → CMP2) are ≥0.95 and consistent across repeated runs.
• Library data frame schema validates: correct column names (group/type labels), no missing values in reference compound names, and wide format compatible with categorate().
• Query chemical names are normalized (case, whitespace, synonym resolution) and successfully resolve to library entries or return explicit 'No match' rather than errors.
• Downstream exactoThese() and mzExacto() calls execute without data type mismatches or missing column errors, confirming library structure is consumable by downstream functions.

Limitations

• Structural matching is restricted to chemical type sets defined by the library; compounds outside these sets will not be matched even if similar compounds exist elsewhere.
• Match scores >0.95 may be unattainable for highly dissimilar or novel query compounds, resulting in false 'No match' designations.
• Library curation is manual; typos or synonym variations in compound names can prevent correct matching (e.g., 'Methyl Salicylate' vs. 'Methyl salicylate').
• The wide-format data frame input_format may become unwieldy with many type sets or large libraries; performance and memory usage are not characterized in the article.

Evidence

• [readme] Library structure and matching: "GroupA = c("Guaiacol", "Tridecane", "Ethyl heptanoate", "Caffeine"); GroupB = c("2-Aminothiazole", "Aspirin", "Octanoic acid", "alpha-Pinene", "Toluene"); chem_library = data.frame(cbind(GroupA,"
• [methods] categorate() function and best-match output: "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] Workflow: loading and passing libraries to categorate(): "Load the query chemical list (Ethyl hexanoate, Methyl salicylate, Octanal, Undecane) and the restricted type library (Type A–E chemical sets) as R data structures. Call categorate() on the query"
• [methods] Match score threshold and output schema: "Extract the best-match results, which identify the highest-scoring structural match (match score >0.95) within each type set for each query chemical"
• [methods] Tool integration for structural matching: "uafR taps into an amazing set of cheminformatics packages -- ChemmineR, fmcsR, webchem"
• [readme] categorate() function purpose: "categorate() is an overpowered function that accesses a broad array of categorical data for searched chemicals"