molecular-network-construction-for-metabolomics
License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution.
Summary
Construct global molecular networks from untargeted metabolomics data to link structurally related compounds and enable propagation of molecular structure annotations. This skill bridges suspect discovery with biotransformation-based annotation by organizing metabolites into networks where anchor compounds with known structures seed annotation of unknown suspects.
When to use
You have untargeted metabolomics data (e.g., LC-MS/MS spectra) and need to organize compounds by structural relatedness to enable structure discovery for unknown metabolites. Specifically, use this skill when you have anchor compounds with known SMILES/InChI and want to infer structures of suspects by finding those suspects in a molecular network derived from the same sample cohort or biological condition.
When NOT to use
- Input is already a curated, single-compound reference spectral library rather than a discovery dataset—molecular networks require many interconnected spectra to build meaningful pathways.
- You have only targeted metabolomics data (focused on a few known compounds)—the strength of networks comes from global scope; targeted data will yield sparse, uninformative networks.
- Your suspects and anchors are not in the same sample cohort or experiment—network edges require spectral similarity; suspects and anchors from unrelated datasets will not appear as neighbors.
Inputs
- Untargeted metabolomics MS/MS spectra (mzML, mzXML, or vendor format)
- Anchor compound reference library (with SMILES/InChI and identifiers)
- Sample metadata and grouping (optional, for network stratification)
- Spectral similarity scoring parameters (cosine function, m/z tolerance)
Outputs
- Global molecular network (node and edge tables)
- Anchor-suspect pair CSV (identifier, mass, anchor ID, anchor SMILES)
- Network visualization (GraphML, GexF, or adjacency matrix)
- Network statistics (degree distribution, connected components, path lengths)
How to apply
Construct a global molecular network by computing spectral similarity (e.g., cosine similarity) between all MS/MS spectra in your metabolomics dataset and connecting spectra above a similarity threshold. Retain both edges (spectral pairs) and node attributes (m/z, retention time, spectral data). Identify known anchor compounds in the network and mark them with their reference SMILES. For each suspect in the molecular network, record its identifier, precursor m/z, and network neighbors (anchors or suspect-neighbor paths). Export anchor-suspect pairs as a CSV with columns: identifier, mass, anchor (compound ID with known structure), and SMILES (the anchor's structure). This organized network becomes the input for biotransformation-based annotation methods, which will rank candidate structures for suspects based on biotransformation rules connecting them to their anchor neighbors.
Related tools
- GNN-SOM (Ranks candidate molecular structures and site-of-metabolism predictions for suspects identified in the molecular network, leveraging graph neural networks trained on biotransformation patterns) — https://github.com/HassounLab/GNN-SOM
- PROXIMAL2 (Generates biotransformation operators that define chemical transformations between anchor and suspect pairs, constraining the chemical feasibility of structure candidates) — https://github.com/HassounLab/PROXIMAL2
- BAM (Orchestrates end-to-end molecular structure discovery using the constructed network of anchor-suspect pairs combined with biotransformation rules and GNN-SOM ranking) — https://github.com/HassounLab/BAM
Evaluation signals
- Network connectivity: molecular network contains ≥1 connected component linking anchors to suspects; no isolated anchor or suspect nodes (degree ≥1 expected for annotatable suspects)
- Anchor-suspect pair CSV completeness: every row has non-null identifier, mass, anchor ID, and valid SMILES; anchor compounds match reference library entries
- Network topology validation: edge-weighting (spectral similarity scores) are within plausible range (e.g., 0–1 for cosine); suspect-to-anchor paths exist and have biologically plausible lengths (≤5–10 edges typical for connected metabolome regions)
- Reproducibility: re-running the network construction with identical parameters on the same spectra produces identical node and edge lists (deterministic spectral similarity scoring)
- Downstream annotation agreement: candidates for suspects rank known correct structures higher than false positives when biotransformation rules are applied to the network-derived anchor-suspect pairs
Limitations
- Network quality depends critically on spectral similarity threshold; too-low thresholds create spurious edges, too-high thresholds fragment the network and isolate suspects from anchors.
- Suspects present in low abundance or with poor-quality MS/MS spectra may have weak or missing spectral similarity edges, becoming unannotatable even if structural neighbors exist.
- Global molecular networks scale computationally with sample size (spectral similarity is O(n²) in the number of spectra); very large untargeted experiments may require sub-sampling or parallelization.
- Network topology alone does not guarantee correct annotation; suspects may be network-connected to anchors via off-target spectral similarity or noise, requiring validation against reference standards or orthogonal evidence.
- The approach requires that suspects and anchors co-occur in the same sample cohort for network linkage; cross-sample or cross-species network merging can introduce artifactual connections.
Evidence
- [other] Open access repository-scale propagated nearest neighbor suspect spectral library for untargeted metabolomics: "Open access repository-scale propagated nearest neighbor suspect spectral library for untargeted metabolomics"
- [readme] the anchor-suspect pairs of interest need to be specified. We have used a set of pairs derived from the molecular network used to create the suspect library: "the anchor-suspect pairs of interest need to be specified. We have used a set of pairs derived from the molecular network used to create the suspect library"
- [readme] molecules_of_interest = csv file of list of queries. It must have an identifier and mass for the suspect as well as anchor and a SMILES that represents the anchor.: "molecules_of_interest = csv file of list of queries. It must have an identifier and mass for the suspect as well as anchor and a SMILES that represents the anchor"
- [other] Molecular structure discovery from untargeted metabolomics data using biotransformation rules and global molecular networking: "Molecular structure discovery from untargeted metabolomics data using biotransformation rules and global molecular networking"
- [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"
1---2name: molecular-network-construction-for-metabolomics-23description: Use when you have untargeted metabolomics data (e.g., LC-MS/MS spectra) and need to organize compounds by structural relatedness to enable structure discovery for unknown metabolites.4license: CC-BY-4.05---67# molecular-network-construction-for-metabolomics89> **License: restricted** — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->10## Summary1112Construct global molecular networks from untargeted metabolomics data to link structurally related compounds and enable propagation of molecular structure annotations. This skill bridges suspect discovery with biotransformation-based annotation by organizing metabolites into networks where anchor compounds with known structures seed annotation of unknown suspects.1314## When to use1516You have untargeted metabolomics data (e.g., LC-MS/MS spectra) and need to organize compounds by structural relatedness to enable structure discovery for unknown metabolites. Specifically, use this skill when you have anchor compounds with known SMILES/InChI and want to infer structures of suspects by finding those suspects in a molecular network derived from the same sample cohort or biological condition.1718## When NOT to use1920- Input is already a curated, single-compound reference spectral library rather than a discovery dataset—molecular networks require many interconnected spectra to build meaningful pathways.21- You have only targeted metabolomics data (focused on a few known compounds)—the strength of networks comes from global scope; targeted data will yield sparse, uninformative networks.22- Your suspects and anchors are not in the same sample cohort or experiment—network edges require spectral similarity; suspects and anchors from unrelated datasets will not appear as neighbors.2324## Inputs2526- Untargeted metabolomics MS/MS spectra (mzML, mzXML, or vendor format)27- Anchor compound reference library (with SMILES/InChI and identifiers)28- Sample metadata and grouping (optional, for network stratification)29- Spectral similarity scoring parameters (cosine function, m/z tolerance)3031## Outputs3233- Global molecular network (node and edge tables)34- Anchor-suspect pair CSV (identifier, mass, anchor ID, anchor SMILES)35- Network visualization (GraphML, GexF, or adjacency matrix)36- Network statistics (degree distribution, connected components, path lengths)3738## How to apply3940Construct a global molecular network by computing spectral similarity (e.g., cosine similarity) between all MS/MS spectra in your metabolomics dataset and connecting spectra above a similarity threshold. Retain both edges (spectral pairs) and node attributes (m/z, retention time, spectral data). Identify known anchor compounds in the network and mark them with their reference SMILES. For each suspect in the molecular network, record its identifier, precursor m/z, and network neighbors (anchors or suspect-neighbor paths). Export anchor-suspect pairs as a CSV with columns: identifier, mass, anchor (compound ID with known structure), and SMILES (the anchor's structure). This organized network becomes the input for biotransformation-based annotation methods, which will rank candidate structures for suspects based on biotransformation rules connecting them to their anchor neighbors.4142## Related tools4344- **GNN-SOM** (Ranks candidate molecular structures and site-of-metabolism predictions for suspects identified in the molecular network, leveraging graph neural networks trained on biotransformation patterns) — https://github.com/HassounLab/GNN-SOM45- **PROXIMAL2** (Generates biotransformation operators that define chemical transformations between anchor and suspect pairs, constraining the chemical feasibility of structure candidates) — https://github.com/HassounLab/PROXIMAL246- **BAM** (Orchestrates end-to-end molecular structure discovery using the constructed network of anchor-suspect pairs combined with biotransformation rules and GNN-SOM ranking) — https://github.com/HassounLab/BAM4748## Evaluation signals4950- Network connectivity: molecular network contains ≥1 connected component linking anchors to suspects; no isolated anchor or suspect nodes (degree ≥1 expected for annotatable suspects)51- Anchor-suspect pair CSV completeness: every row has non-null identifier, mass, anchor ID, and valid SMILES; anchor compounds match reference library entries52- Network topology validation: edge-weighting (spectral similarity scores) are within plausible range (e.g., 0–1 for cosine); suspect-to-anchor paths exist and have biologically plausible lengths (≤5–10 edges typical for connected metabolome regions)53- Reproducibility: re-running the network construction with identical parameters on the same spectra produces identical node and edge lists (deterministic spectral similarity scoring)54- Downstream annotation agreement: candidates for suspects rank known correct structures higher than false positives when biotransformation rules are applied to the network-derived anchor-suspect pairs5556## Limitations5758- Network quality depends critically on spectral similarity threshold; too-low thresholds create spurious edges, too-high thresholds fragment the network and isolate suspects from anchors.59- Suspects present in low abundance or with poor-quality MS/MS spectra may have weak or missing spectral similarity edges, becoming unannotatable even if structural neighbors exist.60- Global molecular networks scale computationally with sample size (spectral similarity is O(n²) in the number of spectra); very large untargeted experiments may require sub-sampling or parallelization.61- Network topology alone does not guarantee correct annotation; suspects may be network-connected to anchors via off-target spectral similarity or noise, requiring validation against reference standards or orthogonal evidence.62- The approach requires that suspects and anchors co-occur in the same sample cohort for network linkage; cross-sample or cross-species network merging can introduce artifactual connections.6364## Evidence6566- [other] Open access repository-scale propagated nearest neighbor suspect spectral library for untargeted metabolomics: "Open access repository-scale propagated nearest neighbor suspect spectral library for untargeted metabolomics"67- [readme] the anchor-suspect pairs of interest need to be specified. We have used a set of pairs derived from the molecular network used to create the suspect library: "the anchor-suspect pairs of interest need to be specified. We have used a set of pairs derived from the molecular network used to create the suspect library"68- [readme] molecules_of_interest = csv file of list of queries. It must have an identifier and mass for the suspect as well as anchor and a SMILES that represents the anchor.: "molecules_of_interest = csv file of list of queries. It must have an identifier and mass for the suspect as well as anchor and a SMILES that represents the anchor"69- [other] Molecular structure discovery from untargeted metabolomics data using biotransformation rules and global molecular networking: "Molecular structure discovery from untargeted metabolomics data using biotransformation rules and global molecular networking"70- [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"
HolobiomicsLab 