Peak Collision Flagging

---
name: peak-collision-flagging
description: 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.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3644
  edam_topics:
  - http://edamontology.org/topic_0659
  - http://edamontology.org/topic_3520
  tools:
  - rMSIcleanup
  - rMSI
  - R
  - rMSIproc
  techniques:
  - MS-imaging
derived_from:
- doi: 10.1186/s13321-020-00449-0
  title: ''
evidence_spans:
- rMSIcleanup is an open-source R package to annotate matrix-related signals in MSI data
- devtools::install_github("prafols/rMSI", ref = "0.8")
- rMSIcleanup is an open-source R package
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_rmsicleanup_ms_imaging_matrix_peak_annot_cq
    doi: 10.1186/s13321-020-00449-0
    title: ''
  dedup_kept_from: coll_rmsicleanup_ms_imaging_matrix_peak_annot_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1186/s13321-020-00449-0
  all_source_dois:
  - 10.1186/s13321-020-00449-0
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

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