# Spectral Peak Network Grouping

> Use when 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.

- Skill: `holobiomicslab/spectral-peak-network-grouping` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/spectral-peak-network-grouping`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/spectral-peak-network-grouping/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/spectral-peak-network-grouping

---


# 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"