HolobiomicsLab spectral-peak-network-grouping
Summary
Group picked peaks from INADEQUATE NMR spectra into networks of peaks originating from the same compound using spectral similarity and co-occurrence patterns. This clustering step bridges peak picking and metabolite database matching by reducing the dimensionality of peak assignments and improving specificity for downstream identification.
When to use
Apply this skill after peak picking has been completed on INADEQUATE NMR spectra and you need to group correlated peaks into compound-specific networks before matching against a metabolite database. Use when your input consists of picked peaks with positional and intensity information but you lack explicit assignments linking peaks to individual compounds.
When NOT to use
- Input peaks have not yet been picked from the raw spectrum; use peak picking first.
- You already have explicit compound assignments or metabolite identifications; clustering adds no value.
- Input consists of 1D NMR or other spectroscopy types not supported by INADEQUATE-specific algorithms.
Inputs
- Picked peaks from PyINETA picking module (with coordinates and intensities)
- INADEQUATE NMR spectrum data (processed, with basic referencing/shifting applied)
Outputs
- Peak-to-cluster assignment mapping file
- Clustered peak networks (peaks grouped by cluster identifier)
- Cluster-annotated peak data compatible with downstream matching module
How to apply
Load picked peaks from the PyINETA picking module output into the clustering module. Apply the PyINETA clustering algorithm to group peaks based on spectral similarity and co-occurrence patterns, which identifies peaks likely originating from the same compound. The algorithm assigns each peak a cluster identifier and generates a mapping file documenting peak-to-cluster assignments. Export clustered peak data in a format compatible with downstream matching and finding modules (typically as a peak network file with cluster IDs). Validate by checking that co-occurring peaks in the same spectral region are grouped together and that the number of clusters is reasonable relative to the expected number of compounds in the sample.
Related tools
- PyINETA (Provides the clustering module (pyineta.clustering) that groups picked peaks into networks using spectral similarity and co-occurrence; orchestrates the full pipeline including picking, clustering, matching, and finding steps.) — https://github.com/edisonomics/PyINETA
- Python (Runtime environment in which PyINETA clustering is executed.)
Examples
python <path_to_pyineta_repo>/run_pyineta.py -c config.ini -s cluster -o output_dir
Evaluation signals
- All picked peaks are assigned to exactly one cluster (no orphaned or multiply-assigned peaks).
- Peaks within the same cluster show consistent spectral similarity metrics and spatial co-localization in the 2D INADEQUATE spectrum.
- The number of clusters is consistent with the number of compounds expected in the sample (or is reduced to a tractable number for downstream database matching).
- Cluster mapping file contains complete, unambiguous peak-to-cluster identifiers with no missing values or malformed entries.
- Downstream matching module successfully processes the clustered peak data and produces metabolite assignments without error.
Limitations
- Clustering quality depends on prior peak-picking accuracy; missed or spurious peaks in the picking step will propagate into clustering.
- The algorithm assumes peaks from the same compound exhibit co-occurrence and spectral similarity patterns; compounds with very weak or overlapping signals may not cluster correctly.
- No changelog is publicly available, making it difficult to assess version-specific improvements or bug fixes to the clustering algorithm.
- The README does not document clustering algorithm parameters (e.g., similarity threshold, distance metric) or their tunability via the config file.
Evidence
- [readme] pyINETA is designed to filter these picked peaks to identify networks of peaks (ideally) coming from the same compound: "It is designed to filter these picked peaks to identify networks of peaks (ideally) coming from the same compound"
- [other] pyINETA implements a clustering module that filters picked peaks to identify networks of peaks from the same compound, operating as a downstream step after peak picking and before matching to metabolite databases.: "pyINETA implements a clustering module that filters picked peaks to identify networks of peaks from the same compound, operating as a downstream step after peak picking and before matching to"
- [other] Apply the PyINETA clustering algorithm to group peaks into networks based on spectral similarity and co-occurrence patterns.: "Apply the PyINETA clustering algorithm to group peaks into networks based on spectral similarity and co-occurrence patterns"
- [other] Assign each peak a cluster identifier and generate a mapping file documenting peak-to-cluster assignments.: "Assign each peak a cluster identifier and generate a mapping file documenting peak-to-cluster assignments"
- [methods] Clustering. .. automodule:: pyineta.clustering: "Clustering
.. automodule:: pyineta.clustering"