Metabolite Structure Annotation Integration

metabolite-structure-annotation-integration

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

Summary

Integrate biotransformation-predicted candidate structures with global molecular networking to annotate untargeted metabolomics features and assign them to molecular families. This skill combines structure predictions from biotransformation rules with spectral similarity clustering to link MS features to putative molecular structures and network communities.

When to use

You have a set of candidate transformed structures generated by biotransformation rules (e.g., from a parent metabolite and enzymatic reaction rules), paired with untargeted LC-MS/MS data (MS1 precursor masses and MS/MS spectra), and you need to assign each detected feature to a predicted structure and cluster it with related metabolites to validate annotations and organize results by molecular family.

When NOT to use

• Input features are already annotated to known reference standards — use targeted approaches instead.
• No biotransformation rules or parent structure anchors are available for the dataset.
• MS/MS spectral data are not available or are of insufficient quality for similarity computation (e.g., <4 significant peaks per spectrum).

Inputs

• Candidate transformed structures (SMILES or molecular format) from biotransformation rules module
• MS/MS spectral data (feature matrix with spectral intensities)
• MS1 precursor masses for each detected feature
• Spectral similarity threshold parameter
• Biotransformation rule parameters and output metadata

Outputs

• Molecular network file (GraphML, JSON, or GXF format)
• Feature annotation table (CSV or TSV) with MS feature ID, predicted structure(s), transformed parent, confidence score, and network cluster ID
• Network graph with annotated nodes and edges representing spectral similarity
• Putative molecular family assignments per feature

How to apply

Load candidate transformed structures from the biotransformation-rules module output and the corresponding MS/MS spectral data. Construct a similarity network by computing spectral similarity scores (e.g., cosine similarity) between all feature pairs in the dataset. Filter edges using a similarity threshold to retain high-confidence spectral matches. Apply graph-based clustering or community detection to identify connected components representing putative molecular families. Annotate each network node with the corresponding candidate structures from biotransformation rules output and associate them with MS1/MS2 features. Export the molecular network in a standard format (GraphML, JSON, or GXF) and generate a feature annotation table linking each MS feature to its predicted structure(s), confidence scores, and network cluster membership.

Related tools

• BAM (End-to-end pipeline for biotransformation-based annotation and global molecular networking integration) — https://github.com/HassounLab/BAM
• PROXIMAL2 (Generates biotransformation rules and candidate transformed structures from parent metabolites and reaction databases) — https://github.com/HassounLab/PROXIMAL2
• GNN-SOM (Predicts site-of-metabolism and assists in ranking enzymatic products for biotransformation annotation) — https://github.com/HassounLab/GNN-SOM

Examples

sh runBAM.sh

Evaluation signals

• Annotation accuracy: Percentage of predicted structures that match reference annotations in a validation dataset (computed by comparing pipeline predictions against known compound identities).
• Network coverage: Proportion of detected MS features successfully annotated with at least one candidate structure and assigned to a molecular family cluster.
• Spectral similarity consistency: Edge quality check — confirm that retained edges in the network have similarity scores above the specified threshold and form coherent clusters.
• Schema validation: Verify that exported molecular network file is valid GraphML/JSON and annotation table contains all required columns (feature ID, structure, mass, cluster ID, confidence).
• Cluster coherence: Manually inspect 3–5 largest clusters to confirm that grouped features share chemically plausible structural relationships or mass differences consistent with the applied biotransformation rules.

Limitations

• Accuracy depends on completeness and specificity of the biotransformation rule dataset (KEGG, RetroRules, or custom); sparse or incorrect rules will reduce candidate quality.
• Spectral similarity-based clustering may conflate isomeric structures or unrelated compounds with similar fragmentation patterns unless additional filters (e.g., MS1 mass tolerance, retention time) are applied.
• Requires pre-computed candidate structures from biotransformation rules; cannot de novo discover novel structures outside the rule set.
• Performance scales with dataset size; large untargeted datasets (>10,000 features) may require parameter tuning and computational resources for similarity matrix construction.
• Network annotation is only as reliable as the anchor molecules and parent structure definitions provided; misidentified anchors will propagate errors through the biotransformation pipeline.

Evidence

• [other] Construct a similarity network by computing spectral similarity scores (e.g., cosine similarity or variant thereof) between all feature pairs in the dataset.: "Construct a similarity network by computing spectral similarity scores (e.g., cosine similarity or variant thereof) between all feature pairs in the dataset."
• [other] Filter edges based on a similarity threshold to retain only high-confidence spectral matches.: "Filter edges based on a similarity threshold to retain only high-confidence spectral matches."
• [other] Apply graph-based clustering or community detection to identify connected components representing putative molecular families.: "Apply graph-based clustering or community detection to identify connected components representing putative molecular families."
• [other] Annotate each network node with the corresponding candidate structures from the biotransformation rules output and associate with MS1/MS2 features.: "Annotate each network node with the corresponding candidate structures from the biotransformation rules output and associate with MS1/MS2 features."
• [other] Export the molecular network in a standard format (e.g., GraphML, JSON, or GXF) and generate a feature annotation table linking each MS feature to its predicted structure(s) and network cluster membership.: "Export the molecular network in a standard format (e.g., GraphML, JSON, or GXF) and generate a feature annotation table linking each MS feature to its predicted structure(s) and network cluster"
• [other] BAM implements a method that combines biotransformation rules and global molecular networking as components for molecular structure discovery from untargeted metabolomics data.: "BAM implements a method that combines biotransformation rules and global molecular networking as components for molecular structure discovery from untargeted metabolomics data."
• [readme] All input information required is specified in runBAM.sh. The desired reaction dataset of interest needs to be specified.: "All input information required is specified in runBAM.sh. The desired reaction dataset of interest needs to be specified."
• [readme] BAM checks if the suspect molecule is known by checking whether the SMILES or InChI is specified in the molecules_of_interest csv file.: "BAM checks if the suspect molecule is known by checking whether the SMILES or InChI is specified in the molecules_of_interest csv file."