--- name: overlapping-peak-detection-interpretation description: Use when annotating matrix-related signals in MSI datasets where chemical formulas or spatial distributions alone are ambiguous, or when multiple ions share nominal m/z values (isobaric peaks). license: CC-BY-4.0 metadata: edam_operation: http://edamontology.org/operation_3632 edam_topics: - http://edamontology.org/topic_3520 - http://edamontology.org/topic_0121 tools: - rMSIcleanup - R - rMSI - 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 - rMSIcleanup is an open-source R package - devtools::install_github("prafols/rMSI", ref = "0.8") 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 --- # overlapping-peak-detection-interpretation ## Summary Detect and document overlapping or isobaric peaks in mass spectrometry imaging data to prevent misclassification of matrix-related ions and transparently justify annotation decisions. This skill interprets overlap status as part of the classification rationale for each m/z feature. ## When to use Apply this skill when annotating matrix-related signals in MSI datasets where chemical formulas or spatial distributions alone are ambiguous, or when multiple ions share nominal m/z values (isobaric peaks). Use it to flag potential misclassification risks before generating the final transparent annotation report, especially in silver-assisted or other matrix-assisted ionization workflows where matrix and analyte ions may overlap in mass space or spatial footprint. ## When NOT to use - Input peak matrix is already deconvolved or has been pre-filtered to remove overlaps—overlapping peak detection would be redundant. - MSI data has insufficient mass resolution (e.g., low-resolution TOF) such that all nominal m/z bins are effectively resolved and isobaric confusion is minimal. - The analysis goal is exploratory visualization only and does not require formal justification of annotation confidence or misclassification risk. ## Inputs - Annotation matrix with classified ion labels (matrix vs. non-matrix) from rMSIcleanup::annotate_matrix() - Peak matrix in rMSIproc format (.zip file containing m/z, intensity, and spatial pixel coordinates) - Processed MSI dataset (.tar file with full spatial distribution and chemical formula information) - Chemical formula and m/z metadata for each annotated ion ## Outputs - Per-annotation overlap status record (presence/absence of isobaric or co-localized peaks) - Classification justification documentation including peak overlap rationale for each ion - Multi-panel visual report with ion spatial map, peak overlap status, and misclassification risk flag - Transparent annotation artifact (PDF or structured report) compiled from all per-annotation overlap assessments ## How to apply For each annotated ion in the rMSIcleanup workflow, retrieve its chemical formula, m/z value, and spatial distribution pattern across the MSI dataset. Use rMSIcleanup's overlapping peak detection feature to identify isobaric or co-localized peaks that could confound classification. Document the peak overlap status (present/absent) for each annotation, capturing both nominal m/z collisions and spatial co-occurrence patterns. Include this overlap status explicitly in the per-annotation justification record. Rank or flag annotations with detected overlaps as higher-risk classifications that require manual review or additional evidence (e.g., high-resolution m/z, orthogonal spatial signatures) before finalizing matrix removal. The rationale is that transparent documentation of overlap prevents silent misclassification and allows downstream users to weight annotations by confidence. ## Related tools - **rMSIcleanup** (Primary tool; provides the overlapping peak detection feature and integration into annotation workflow) — https://github.com/gbaquer/rMSIcleanup - **rMSIproc** (Data preprocessing and format management; loads/stores peak matrix in required format) — https://github.com/prafols/rMSIproc - **rMSI** (MSI data loading and spatial distribution querying for overlap detection) — https://github.com/prafols/rMSI - **R** (Execution environment for rMSIcleanup and dependent packages) ## Examples ``` rMSIcleanup::annotate_matrix(pks, "Ag1", full); rMSIcleanup::generate_pdf_report(results, pks, full, "test_with_overlaps", folder="/home/user/") ``` ## Evaluation signals - Overlap status (present/absent) is recorded and exported for every annotated ion in the justification artifact. - Overlapping peaks are visibly flagged or highlighted in the multi-panel visual report, distinguishing high-overlap from non-overlapping annotations. - Classification rationale text explicitly mentions peak overlap status as part of the justification for matrix vs. non-matrix decision. - Ions with detected overlaps are tagged with a misclassification risk level (low/medium/high) and listed separately for manual review. - The generated PDF report includes a summary table or histogram of overlap prevalence across the dataset, enabling meta-assessment of annotation confidence. ## Limitations - Overlapping peak detection effectiveness depends on mass resolution and accuracy of the input m/z calibration; low-resolution data may not resolve true isobaric peaks. - Spatial overlap detection relies on pixel-level co-localization; at coarse spatial sampling or high feature abundance, false-positive overlap signals may inflate risk flags. - The README and article do not specify the exact overlap detection algorithm (e.g., m/z tolerance window, spatial overlap threshold), limiting reproducibility and tuning options for specialized applications. - Overlapping peak detection output is presented as binary (overlap present/absent) rather than a continuous confidence metric, which may obscure borderline or ambiguous cases. ## 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] For each annotated ion, retrieve its chemical formula, m/z value, and spatial distribution pattern across the MSI dataset. Identify overlapping or isobaric peaks using the overlapping peak detection feature to document potential misclassification risks.: "For each annotated ion, retrieve its chemical formula, m/z value, and spatial distribution pattern across the MSI dataset. Identify overlapping or isobaric peaks using the overlapping peak detection" - [intro] the package generates a visual report to transparently justify each annotation: "the package generates a visual report to transparently justify each annotation" - [other] Generate a multi-panel visual report for each annotation showing: ion spatial map, chemical formula identifier, peak overlap status, and classification justification (matrix vs. non-matrix).: "Generate a multi-panel visual report for each annotation showing: ion spatial map, chemical formula identifier, peak overlap status, and classification justification" - [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"