# Cluster Assignment Mapping

> Use when after density-based clustering (e.g., DBSCAN) has been performed on a sparse pairwise distance matrix derived from MS/MS spectra nearest neighbor indexes.

- Skill: `holobiomicslab/cluster-assignment-mapping` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/cluster-assignment-mapping`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/cluster-assignment-mapping/raw
- Safety review: pending
- 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/cluster-assignment-mapping

---


# cluster-assignment-mapping

## Summary

Map spectrum identifiers to their assigned cluster IDs after density-based clustering on a sparse pairwise distance matrix. This skill produces a machine-readable assignment table and summary statistics that document cluster composition and quality.

## When to use

After density-based clustering (e.g., DBSCAN) has been performed on a sparse pairwise distance matrix derived from MS/MS spectra nearest neighbor indexes. Use this skill when you need to export cluster membership in a structured format suitable for downstream analysis, validation, or representative spectrum selection.

## When NOT to use

- The clustering step has not yet been performed—apply density-based clustering first.
- Input spectra have already been assigned to clusters by an external method and you only need to report the pre-computed mapping without re-clustering.
- The sparse pairwise distance matrix is missing or incompatible with the clustering algorithm (e.g., wrong format or corrupted data).

## Inputs

- Cluster assignments from density-based clustering algorithm (e.g., DBSCAN output with cluster ID per spectrum)
- Spectrum identifiers or scan numbers corresponding to each clustered spectrum
- Optional: original peak file metadata for spectrum name enrichment

## Outputs

- Comma-separated file (CSV) mapping spectrum identifiers to cluster IDs (one spectrum per line)
- Cluster summary statistics table (number of clusters, cluster sizes, noise count)
- Optional: cluster representative spectra list or MGF file for downstream validation

## How to apply

Load the clustering result (cluster IDs and spectrum identifiers) from the density-based clustering step and serialize it as a comma-separated table with one spectrum per row and its assigned cluster label per column. Simultaneously compute and report summary statistics including the total number of clusters formed, per-cluster size distribution, and the count of unclustered (noise) spectra if applicable. The mapping preserves the spectral identifiers (e.g., scan number, spectrum name) to enable traceability and cross-referencing with the original peak files. Quality can be assessed by verifying cluster sizes are non-empty and reasonable relative to the input spectrum count.

## Related tools

- **falcon** (Performs end-to-end spectrum clustering including density-based clustering and cluster assignment export; outputs CSV file with spectrum-to-cluster mappings) — https://github.com/bittremieux/falcon
- **DBSCAN** (Core density-based clustering algorithm applied to sparse pairwise distance matrix to generate cluster assignments)

## Examples

```
falcon peak/*.mzml falcon --export_representatives --precursor_tol 20 ppm --fragment_tol 0.05 --eps 0.10
```

## Evaluation signals

- CSV output file is valid and parseable, with one spectrum identifier and one cluster ID per row
- Cluster ID values are consistent integers or identifiers with no gaps or NaN entries for assigned spectra
- Cluster size distribution is non-pathological: no single cluster contains >90% of spectra unless data is homogeneous
- Summary statistics (total clusters, per-cluster sizes) match manual count of unique cluster IDs and row counts in output
- Spectrum identifiers in the mapping are traceable back to the original peak file (mzML, mzXML, or MGF format)

## Limitations

- Cluster purity and biological validity depend critically on the eps parameter (maximum cosine distance): values between 0.05 and 0.15 are typical for proteomics, but metabolomics and top-down data may require different thresholds.
- Noise spectra (assigned to cluster ID −1 or 0 in DBSCAN) are included in the mapping but represent unclustered spectra; their prevalence may indicate insufficient nearest neighbor coverage or overly stringent eps.
- The mapping reflects only the density-based clustering result; it does not assess biological accuracy without manual validation or external ground truth (e.g., peptide sequence databases).
- Large-scale datasets (millions of spectra) may produce very large CSV files; consider chunking or using compressed formats for downstream storage.

## Evidence

- [other] Output cluster assignments as a table mapping spectrum identifiers to cluster IDs, and generate summary statistics (cluster sizes, number of clusters formed).: "Output cluster assignments as a table mapping spectrum identifiers to cluster IDs, and generate summary statistics (cluster sizes, number of clusters formed)."
- [readme] falcon takes peak files (in the mzML, mzXML, or MGF format) as input and exports the clustering result as a comma-separated file with each MS/MS spectrum and its cluster label on a single line.: "exports the clustering result as a comma-separated file with each MS/MS spectrum and its cluster label on a single line"
- [readme] This will cluster all MS/MS spectra in mzML files in the `peak` directory with the specified settings and write (i) the cluster assignments to the `falcon.csv` file, and (ii) the cluster representatives to the `falcon.mgf` file.: "write (i) the cluster assignments to the `falcon.csv` file, and (ii) the cluster representatives to the `falcon.mgf` file"
- [intro] Finally, density-based clustering is performed to group similar spectra into clusters.: "density-based clustering is performed to group similar spectra into clusters"
- [readme] The DBSCAN algorithm is used to find spectra that are close to each other and that form a dense data subspace, and group them into clusters.: "The DBSCAN algorithm is used to find spectra that are close to each other and that form a dense data subspace, and group them into clusters."