Mass spectral feature grouping

mass-spectral-feature-grouping

Summary

Group MS features into molecular families by constructing a similarity network from MS/MS spectral data, filtering edges by similarity threshold, and applying graph-based clustering to identify connected components. This groups features that likely derive from related molecular structures or biotransformation products.

When to use

You have untargeted metabolomics MS/MS spectra from multiple features and need to identify which features belong to the same molecular family or are related by biotransformation. Use this skill when you want to collapse high-dimensional feature data into interpretable molecular groups before or after structure annotation.

When NOT to use

• Your input is already a feature table or quantification matrix without MS/MS spectra — you need the actual spectral similarity information.
• You have only targeted quantification data for known metabolites and do not need to discover molecular families.
• MS/MS spectral data are of very low quality or missing for most features, making similarity computation unreliable.

Inputs

• MS/MS spectral data matrix (feature × m/z intensity pairs)
• Feature metadata (e.g., retention time, precursor m/z, feature ID)
• Similarity threshold parameter (numeric, unitless or %; e.g., 0.5–0.9 for cosine similarity)

Outputs

• Molecular network in standard graph format (GraphML, JSON, or GXF)
• Cluster/community assignments (feature ID → cluster ID mapping)
• Network node list with cluster membership and optionally candidate structure annotations
• Feature annotation table linking MS features to predicted structures and network cluster membership

How to apply

Load all MS/MS spectral data for your feature set. Compute spectral similarity scores (e.g., cosine similarity) between all feature pairs to construct a complete similarity network. Filter edges by applying a similarity threshold (e.g., retain only pairs above a cutoff value) to retain only high-confidence spectral matches and reduce noise. Apply graph-based clustering or community detection algorithms (e.g., modularity optimization or connected-component analysis) to partition the filtered network into clusters. Each cluster represents a putative molecular family. Optionally annotate each node in the resulting clusters with candidate structures from biotransformation rule predictions or reference spectral libraries to validate family membership.

Related tools

• BAM (Implements the complete biotransformation-based annotation workflow including global molecular networking for feature grouping and structure discovery) — https://github.com/HassounLab/BAM
• PROXIMAL2 (Upstream tool used by BAM to generate biotransformation rules and operator sets for candidate structure prediction) — https://github.com/HassounLab/PROXIMAL2
• GNN-SOM (Integrated with BAM for site-of-metabolism prediction and ranking of promiscuous enzymatic products) — https://github.com/HassounLab/GNN-SOM

Evaluation signals

• Network connectivity statistics: verify that the filtered network has expected edge density and connected component size distribution (no single giant component for random data).
• Cluster homogeneity: check that features within the same cluster have spectral similarity scores above the applied threshold, and inter-cluster pairs fall below it.
• Annotation coherence: if candidate structures are available, verify that features in the same cluster are annotated with structures related by plausible biotransformation rules (e.g., oxidation, methylation, conjugation).
• GraphML/JSON schema validation: ensure exported network files conform to the declared graph format and contain required node/edge attributes (node IDs, similarity scores, cluster IDs).
• Feature coverage: verify that all input features appear in the output network and are assigned to exactly one cluster (no orphaned or multiply-assigned features).

Limitations

• Similarity threshold selection is not fully automated and must be tuned for your spectral data type and quality; inappropriate thresholds can merge unrelated families or fragment true families.
• Clustering quality depends on MS/MS spectral data quality; low signal-to-noise or incomplete fragmentation patterns reduce discriminative power for similarity computation.
• The method is sensitive to the choice of similarity metric (cosine, modified cosine, spectral entropy distance); different metrics may yield different network structures.
• No changelog is provided in the repository, limiting tracking of updates or bug fixes to the networking implementation.
• The skill identifies spectral similarity and graph connectivity but does not directly validate that grouped features arise from the same biological compound or biotransformation product without downstream annotation.

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"
• [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."
• [intro] BAM method uses biotransformation rules and global molecular networking for structure annotation: "BAM method uses biotransformation rules and global molecular networking for structure annotation"
• [other] Export the molecular network in a standard format (e.g., GraphML, JSON, or GXF) and generate a feature annotation table: "Export the molecular network in a standard format (e.g., GraphML, JSON, or GXF) and generate a feature annotation table"