HolobiomicsLab Spatial-overlap analysis for imaging mass spectrometry
Summary
Identifies and flags overlapping peaks and isobaric ions in mass spectrometry imaging (MSI) data by analyzing m/z coincidence and spatial distribution patterns across tissue. This prevents misclassification of chemically distinct ions during matrix-related signal annotation.
When to use
When annotating matrix-related peaks in MSI datasets where candidate peaks have identical or near-identical m/z values (isobaric ions), or when multiple peaks exhibit overlapping spatial distributions across the tissue image that could confound downstream annotation filtering.
When NOT to use
- Input peaks are already validated as unique or confirmed to be from distinct chemical species by orthogonal methods (e.g., tandem MS or NMR).
- Analyzing single-point mass spectra without spatial distribution data; overlap detection requires 2D or 3D tissue image coordinates.
- Working with pre-processed data where overlapping peaks have already been resolved or merged by the instrument vendor.
Inputs
- Mass spectrometry imaging (MSI) data in rMSIproc format (.tar)
- Extracted peak list / peak matrix (.zip)
- Chemical formula annotations (optional, for context)
Outputs
- Binary overlap flag table (CSV) mapping peak identifiers to overlap status
- Annotated peak matrix with overlap classification
- Visual report justifying each overlap annotation
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 by calling annotate_matrix(), which identifies candidate peaks with matching or near-matching m/z values and examines their spatial co-localization patterns across the tissue. The algorithm generates binary overlap flags (flagged for overlapped, unflagged for unique peaks) mapped to each peak identifier. Export the overlap flag table as a structured CSV file and use these flags to filter downstream annotation decisions, preventing ambiguous or overlapped peaks from being misassigned to matrix or analyte categories.
Related tools
- rMSIcleanup (Core package providing annotate_matrix() function for overlapping peak detection and generate_pdf_report() for visual justification of flags) — https://github.com/gbaquer/rMSIcleanup
- rMSI (Loads and manages MSI data objects; provides spatial coordinate system for overlap analysis) — https://github.com/prafols/rMSI
- rMSIproc (Preprocesses imzML files and manages peak matrix format (.zip) for input to overlap detection) — https://github.com/prafols/rMSIproc
- R (Runtime environment for rMSIcleanup and dependent packages)
Examples
rMSIcleanup::annotate_matrix(pks, "Ag1", full); rMSIcleanup::generate_pdf_report(results, pks, full, "overlap_report", folder="./")
Evaluation signals
- Overlap flag table contains no missing values and all peak identifiers map to exactly one flag status (flagged or unflagged).
- Peaks flagged as overlapped exhibit < N ppm m/z difference threshold AND spatial Pearson correlation > threshold across tissue image; unflagged peaks do not meet both criteria.
- Visual PDF report displays side-by-side spatial heatmaps for each flagged peak pair, with overlapping regions highlighted to justify the flag assignment.
- Downstream annotation step (remove_matrix function) successfully filters flagged peaks without throwing errors, producing a reduced peak matrix with consistent dimensionality.
- Manual spot-check: randomly sampled 10–20 flagged peaks show genuine m/z overlap and/or spatial co-localization; no false positives where unrelated peaks were incorrectly flagged.
Limitations
- Algorithm depends on peak picking quality upstream; noisy or poorly resolved peaks may generate false overlap flags or miss genuine overlaps.
- Isobaric ion resolution relies on m/z accuracy of the mass spectrometer; instruments with lower mass resolution (> 5 ppm) may conflate distinct ions.
- Spatial overlap detection assumes tissue heterogeneity; in highly uniform regions or homogeneous tissue, spatial correlation alone may not distinguish isobaric pairs.
- No discussion of tuning parameters (m/z tolerance, spatial correlation threshold) provided in the article; users must select thresholds empirically.
- Currently designed for 2D MSI workflows; extension to 3D tissue imaging or high-dimensional spatial data is not documented.
Evidence
- [intro] overlapping peak detection feature designed 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] identify candidate peaks with identical or near-identical m/z values 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"
- [other] binary overlap flags for each candidate peak: "Generate binary overlap flags for each candidate peak (flagged=overlapped, unflagged=unique)."
- [intro] algorithm takes into account the chemical formula and the spatial distribution: "The algorithm takes into account the chemical formula and the spatial distribution to determine which ions are matrix-related"
- [intro] visual report to transparently justify each annotation: "the package generates a visual report to transparently justify each annotation"
- [readme] rMSIcleanup is an open-source R package to annotate matrix-related signals in MSI data: "rMSIcleanup is an open-source R package to annotate matrix-related signals in MSI data."
- [readme] workflow for loading and annotating data: "pks<-rMSIproc::LoadPeakMatrix("[Full Path to Peak Matrix (.zip)]"); results<-rMSIcleanup::annotate_matrix(pks,"Ag1",full)"