# Peak Collision Flagging

> Use when you have extracted a peak list from MSI data and need to annotate matrix-related signals, but overlapping peaks or isobaric ions (ions with identical or near-identical m/z values) risk being misclassified.

- Skill: `holobiomicslab/peak-collision-flagging` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/peak-collision-flagging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/peak-collision-flagging/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/peak-collision-flagging

---


# peak-collision-flagging

## Summary

Identify and flag overlapped or isobaric ions in mass spectrometry imaging data to prevent their misclassification during matrix-related signal annotation. This skill uses m/z matching and spatial distribution analysis to generate binary overlap flags for each candidate peak.

## When to use

Apply this skill when you have extracted a peak list from MSI data and need to annotate matrix-related signals, but overlapping peaks or isobaric ions (ions with identical or near-identical m/z values) risk being misclassified. Use it before downstream annotation filtering to ensure only true unique peaks are retained.

## When NOT to use

- Input peak list has already been filtered for overlapping ions by another method
- Analysis does not require distinction between matrix-related and analyte ions
- MSI data lacks sufficient spatial resolution to reliably measure peak overlap across tissue

## Inputs

- Mass spectrometry imaging (MSI) data in rMSI format (.tar)
- Extracted peak list in rMSIproc format (.zip)
- Peak matrix with m/z values and spatial distribution information

## Outputs

- Binary overlap flag table (CSV) mapping peak identifiers to overlap status
- Annotated peak list with flagged=overlapped or unflagged=unique assignments

## How to apply

Load the MSI data and extracted peak list into R using rMSI and rMSIproc. Apply the overlapping peak detection algorithm in rMSIcleanup to identify candidate peaks with identical or near-identical m/z values and peaks with overlapping spatial distributions across the tissue image. The algorithm generates a binary overlap flag for each peak (flagged=overlapped, unflagged=unique), taking into account both the chemical formula and spatial distribution to distinguish matrix-related from analyte ions. Export the overlap flag table as a structured CSV file mapping peak identifiers to overlap status. This flagging step prevents downstream misclassification by explicitly marking peaks that share m/z or spatial characteristics before annotation is finalized.

## Related tools

- **rMSIcleanup** (Primary tool implementing the overlapping peak detection algorithm and generating overlap flags) — https://github.com/gbaquer/rMSIcleanup
- **rMSI** (Loads and manages MSI data in R; required dependency for rMSIcleanup) — https://github.com/prafols/rMSI
- **rMSIproc** (Processes raw imzML files into rMSIproc format and loads peak matrices) — https://github.com/prafols/rMSIproc
- **R** (Runtime environment for all package operations)

## Examples

```
results <- rMSIcleanup::annotate_matrix(pks, "Ag1", full); pks_clean <- rMSIcleanup::remove_matrix(pks, results)
```

## Evaluation signals

- Overlap flag table is generated with no missing or null entries for any peak identifier
- Binary flags (flagged vs. unflagged) are consistent with manual inspection of m/z values and spatial distribution plots
- Peaks flagged as overlapped show near-identical m/z values (within instrument mass accuracy) or spatial overlap in tissue images
- Downstream annotation filtering correctly removes or flags overlapped peaks without false negatives on true unique peaks
- Visual report generated by generate_pdf_report() transparently shows flagged peaks with justification based on m/z and spatial criteria

## Limitations

- Accuracy depends on peak extraction quality and m/z calibration; poorly calibrated or noisy spectra may produce false overlap flags
- Spatial overlap detection relies on imaging resolution; low-resolution datasets may conflate distant peaks as spatially overlapped
- The algorithm's treatment of 'near-identical' m/z thresholds is not explicitly parameterized in the README; precision depends on instrument mass accuracy and default settings in rMSIcleanup
- Isobaric ions with identical chemical formulas cannot be distinguished by this approach and will be flagged as collisions regardless of biological identity

## Evidence

- [intro] The package incorporates an overlapping peak detection feature to prevent misclassification of overlapped or isobaric ions: "the package incorporates an overlapping peak detection feature to prevent misclassification of overlapped or isobaric ions"
- [other] Apply overlapping peak detection algorithm to identify candidate peaks with identical or near-identical m/z values (isobaric ions) and peaks with overlapping spatial distributions: "Apply overlapping peak detection algorithm in rMSIcleanup to identify candidate peaks with identical or near-identical m/z values (isobaric ions) and peaks with overlapping spatial distributions"
- [intro] The algorithm takes into account the chemical formula and the spatial distribution to determine which ions are matrix-related: "The algorithm takes into account the chemical formula and the spatial distribution to determine which ions are matrix-related"
- [other] Generate binary overlap flags for each candidate peak: "Generate binary overlap flags for each candidate peak (flagged=overlapped, unflagged=unique)"