Peak collision flagging

peak-collision-flagging

License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->

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