Compound clustering from inadequate spectra

compound-clustering-from-inadequate-spectra

Summary

Group picked peaks from INADEQUATE NMR spectra into networks representing individual compounds using spectral similarity and co-occurrence patterns. This clustering step bridges peak picking and metabolite database matching, reducing false positives by associating only peaks likely originating from the same chemical entity.

When to use

After peak picking has identified individual signals in an INADEQUATE NMR spectrum, apply this skill when you need to collapse thousands of individual peaks into fewer, more interpretable compound-level peak networks. Use it when the downstream goal is matching peak networks to a metabolite database rather than analyzing individual peaks, or when you need a mapping of peaks to their parent compounds for downstream finding and matching modules.

When NOT to use

• Input is already a pre-clustered or pre-annotated database of metabolites; use clustering only on de novo picked peaks
• Spectrum contains only isolated, non-overlapping peaks with no co-occurrence patterns; clustering requires multi-peak associations
• Downstream analysis requires individual peak-level resolution rather than compound-level networks

Inputs

• Picked peaks from PyINETA.picking module (list with peak coordinates, intensities, and picking metadata)
• INADEQUATE NMR spectrum reference or peak occurrence matrix

Outputs

• Peak-to-cluster mapping file (peak ID → cluster ID)
• Clustered peak dataset with cluster identifiers attached
• Cluster-level summary statistics (peaks per cluster, cluster intensity distributions)

How to apply

Load the output from the peak-picking module (picked peak list with coordinates and intensities). Apply PyINETA's clustering algorithm, which groups peaks based on spectral similarity metrics and co-occurrence patterns—peaks that frequently appear together in the spectrum and have similar spectral characteristics are assigned to the same cluster. Each peak receives a unique cluster identifier, and a mapping file is generated documenting peak-to-cluster assignments. Export the clustered data in a format compatible with the downstream matching module, preserving both the cluster identifiers and the original peak metadata. Verify that cluster assignments are consistent and that no single cluster contains an implausibly large number of peaks for a single compound.

Related tools

• PyINETA (Implements the clustering module (pyineta.clustering) that groups peaks into networks based on spectral similarity and co-occurrence) — https://github.com/edisonomics/PyINETA
• Python (Runtime environment for PyINETA clustering execution)

Examples

python <path_to_pyineta_repo>/run_pyineta.py -c config.ini -s cluster -o output_dir

Evaluation signals

• Cluster identifiers are assigned to all input peaks with no missing or duplicate assignments
• Peak-to-cluster mapping file is well-formed and references valid cluster IDs for each input peak
• Cluster size distribution is reasonable (no single cluster contains an implausible fraction of all peaks, e.g. >50%)
• Clustered peak output is compatible with and accepted by downstream PyINETA matching module without format errors
• Peaks within the same cluster exhibit correlated intensity patterns or spectral similarity above the algorithm's internal threshold

Limitations

• Clustering accuracy depends on quality of preceding peak picking; noisy or over-picked spectra may produce artifactual clusters
• Algorithm assumes peaks from the same compound show co-occurrence and spectral similarity; highly variable or fragmented signals from a single compound may be split across clusters
• No changelog available in repository, limiting visibility into algorithm changes or parameter tuning across versions
• Clustering module documentation does not specify distance metrics, similarity thresholds, or linkage criteria explicitly in the provided materials

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] Clustering module operates as a downstream step after peak picking and before matching to metabolite databases: "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"
• [other] Clustering algorithm groups peaks 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"
• [methods] Clustering is one of the documented modules in PyINETA's workflow: "Clustering

---

.. automodule:: pyineta.clustering"

• [other] Output format must be compatible with downstream matching and finding modules: "Export the clustered peak data in a format compatible with downstream matching and finding modules"