chemical-formula-annotation-mapping
Summary
Map detected m/z peaks to chemical formulas and classify them as matrix-related or non-matrix ions by integrating chemical identity with spatial distribution patterns across the MSI dataset. This skill enables transparent, justified annotation of matrix signals in mass spectrometry imaging.
When to use
Apply this skill when you have processed MSI peak data (in rMSIproc format) and need to distinguish matrix-related ions from analyte signals. Specifically: (1) you have a peak matrix with m/z values and spatial intensity maps; (2) you have a reference matrix identity (e.g., 'Ag1' for silver); (3) you want to document classification rationale to prevent downstream misidentification of matrix artifacts as genuine analyte peaks.
When NOT to use
- Input is raw imzML without prior processing via rMSIproc—use ProcessWizard() first.
- Matrix identity is unknown or not specified—the algorithm requires a reference matrix formula to classify peaks.
- Peak matrix already manually curated or pre-filtered for matrix removal—redundant re-annotation may introduce inconsistency.
Inputs
- Peak matrix file (.zip format from rMSIproc)
- Processed MSI dataset (.tar format from rMSI)
- Matrix identity string (e.g., 'Ag1' for silver)
- m/z values and spatial intensity maps per peak
Outputs
- Annotation results object containing classification (matrix vs. non-matrix) for each peak
- Per-annotation visual report (multi-panel PDF) with spatial map, chemical formula, overlap status, and justification
- Compiled transparent documentation artifact
- Clean peak matrix (.zip) with matrix annotations removed (optional downstream step)
How to apply
Load the peak matrix (.zip) and processed MSI data (.tar) using rMSIproc and rMSI. For each detected peak, retrieve its m/z value, chemical formula, and spatial distribution pattern across tissue pixels. Invoke rMSIcleanup's annotate_matrix() function with the matrix identity (e.g., 'Ag1' for silver-assisted LADI) as the reference. The algorithm integrates chemical formula matching with spatial distribution analysis: peaks matching known matrix formula(e) that show uniform spatial coverage are classified as matrix-related; peaks with identical or near-identical m/z (isobaric or overlapping) are flagged by the overlapping peak detection feature to document misclassification risk. Generate a visual report via generate_pdf_report() showing per-annotation justification (ion spatial map, formula identifier, peak overlap status, classification decision).
Related tools
- rMSIcleanup (Primary annotation engine; executes annotate_matrix() to classify ions as matrix-related based on chemical formula and spatial distribution, and generate_pdf_report() to produce transparent justification per annotation.) — https://github.com/gbaquer/rMSIcleanup
- rMSI (Loads and manages processed MSI data (.tar); provides spatial intensity maps and peak intensity data for formula matching and distribution analysis.) — https://github.com/prafols/rMSI
- rMSIproc (Loads peak matrix (.zip) and manages data I/O; provides ProcessWizard() for converting raw imzML to rMSIproc format if needed.) — https://github.com/prafols/rMSIproc
- R (Runtime environment and scripting language for rMSIcleanup and dependency packages.)
Examples
results<-rMSIcleanup::annotate_matrix(pks,"Ag1",full); rMSIcleanup::generate_pdf_report(results,pks,full,"test",folder="/home/gbaquer/")
Evaluation signals
- All detected peaks are assigned a classification (matrix vs. non-matrix) with no missing annotations.
- Visual report contains a multi-panel figure for each annotated ion, including spatial map, chemical formula label, and classification rationale text.
- Peaks flagged by overlapping peak detection feature are documented in the report with isobaric/overlap conflict noted.
- Spatial distribution of classified matrix peaks should show uniform or matrix-like coverage (not isolated to single regions or analyte-rich areas).
- Removed matrix peak matrix (.zip output) has fewer peaks than input, and removed peaks correspond exactly to those marked matrix-related in the report.
Limitations
- Algorithm accuracy depends on accurate chemical formula prediction; m/z alone is insufficient without formula assignment.
- Overlapping peak detection may not resolve ambiguous cases where analyte and matrix signals truly co-localize spatially.
- Requires a priori knowledge of the matrix compound identity; automatic matrix detection is not addressed in this workflow.
- Visual report transparency is limited by peak count; very large datasets may produce unwieldy multi-hundred-page PDFs.
Evidence
- [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"
- [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"
- [intro] The package generates a visual report to transparently justify each annotation: "the package generates a visual report to transparently justify each annotation"
- [other] For each annotated ion, retrieve its chemical formula, m/z value, and spatial distribution pattern across the MSI dataset: "For each annotated ion, retrieve its chemical formula, m/z value, and spatial distribution pattern across the MSI dataset"
- [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 (matrix vs. non-matrix)"
- [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] results<-rMSIcleanup::annotate_matrix(pks,"Ag1",full); rMSIcleanup::generate_pdf_report(results,pks,full,"test",folder="/home/gbaquer/"): "results<-rMSIcleanup::annotate_matrix(pks,"Ag1",full); rMSIcleanup::generate_pdf_report(results,pks,full,"test",folder="/home/gbaquer/")"
1---2name: chemical-formula-annotation-mapping3description: Use when you have processed MSI peak data (in rMSIproc format) and need to distinguish matrix-related ions from analyte signals. Specifically: (1) you have a peak matrix with m/z values and spatial intensity maps; (2) you have a reference matrix identity (e.g., 'Ag1' for silver);4license: CC-BY-4.05---67# chemical-formula-annotation-mapping89## Summary1011Map detected m/z peaks to chemical formulas and classify them as matrix-related or non-matrix ions by integrating chemical identity with spatial distribution patterns across the MSI dataset. This skill enables transparent, justified annotation of matrix signals in mass spectrometry imaging.1213## When to use1415Apply this skill when you have processed MSI peak data (in rMSIproc format) and need to distinguish matrix-related ions from analyte signals. Specifically: (1) you have a peak matrix with m/z values and spatial intensity maps; (2) you have a reference matrix identity (e.g., 'Ag1' for silver); (3) you want to document classification rationale to prevent downstream misidentification of matrix artifacts as genuine analyte peaks.1617## When NOT to use1819- Input is raw imzML without prior processing via rMSIproc—use ProcessWizard() first.20- Matrix identity is unknown or not specified—the algorithm requires a reference matrix formula to classify peaks.21- Peak matrix already manually curated or pre-filtered for matrix removal—redundant re-annotation may introduce inconsistency.2223## Inputs2425- Peak matrix file (.zip format from rMSIproc)26- Processed MSI dataset (.tar format from rMSI)27- Matrix identity string (e.g., 'Ag1' for silver)28- m/z values and spatial intensity maps per peak2930## Outputs3132- Annotation results object containing classification (matrix vs. non-matrix) for each peak33- Per-annotation visual report (multi-panel PDF) with spatial map, chemical formula, overlap status, and justification34- Compiled transparent documentation artifact35- Clean peak matrix (.zip) with matrix annotations removed (optional downstream step)3637## How to apply3839Load the peak matrix (.zip) and processed MSI data (.tar) using rMSIproc and rMSI. For each detected peak, retrieve its m/z value, chemical formula, and spatial distribution pattern across tissue pixels. Invoke rMSIcleanup's annotate_matrix() function with the matrix identity (e.g., 'Ag1' for silver-assisted LADI) as the reference. The algorithm integrates chemical formula matching with spatial distribution analysis: peaks matching known matrix formula(e) that show uniform spatial coverage are classified as matrix-related; peaks with identical or near-identical m/z (isobaric or overlapping) are flagged by the overlapping peak detection feature to document misclassification risk. Generate a visual report via generate_pdf_report() showing per-annotation justification (ion spatial map, formula identifier, peak overlap status, classification decision).4041## Related tools4243- **rMSIcleanup** (Primary annotation engine; executes annotate_matrix() to classify ions as matrix-related based on chemical formula and spatial distribution, and generate_pdf_report() to produce transparent justification per annotation.) — https://github.com/gbaquer/rMSIcleanup44- **rMSI** (Loads and manages processed MSI data (.tar); provides spatial intensity maps and peak intensity data for formula matching and distribution analysis.) — https://github.com/prafols/rMSI45- **rMSIproc** (Loads peak matrix (.zip) and manages data I/O; provides ProcessWizard() for converting raw imzML to rMSIproc format if needed.) — https://github.com/prafols/rMSIproc46- **R** (Runtime environment and scripting language for rMSIcleanup and dependency packages.)4748## Examples4950```51results<-rMSIcleanup::annotate_matrix(pks,"Ag1",full); rMSIcleanup::generate_pdf_report(results,pks,full,"test",folder="/home/gbaquer/")52```5354## Evaluation signals5556- All detected peaks are assigned a classification (matrix vs. non-matrix) with no missing annotations.57- Visual report contains a multi-panel figure for each annotated ion, including spatial map, chemical formula label, and classification rationale text.58- Peaks flagged by overlapping peak detection feature are documented in the report with isobaric/overlap conflict noted.59- Spatial distribution of classified matrix peaks should show uniform or matrix-like coverage (not isolated to single regions or analyte-rich areas).60- Removed matrix peak matrix (.zip output) has fewer peaks than input, and removed peaks correspond exactly to those marked matrix-related in the report.6162## Limitations6364- Algorithm accuracy depends on accurate chemical formula prediction; m/z alone is insufficient without formula assignment.65- Overlapping peak detection may not resolve ambiguous cases where analyte and matrix signals truly co-localize spatially.66- Requires a priori knowledge of the matrix compound identity; automatic matrix detection is not addressed in this workflow.67- Visual report transparency is limited by peak count; very large datasets may produce unwieldy multi-hundred-page PDFs.6869## Evidence7071- [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"72- [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"73- [intro] The package generates a visual report to transparently justify each annotation: "the package generates a visual report to transparently justify each annotation"74- [other] For each annotated ion, retrieve its chemical formula, m/z value, and spatial distribution pattern across the MSI dataset: "For each annotated ion, retrieve its chemical formula, m/z value, and spatial distribution pattern across the MSI dataset"75- [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 (matrix vs. non-matrix)"76- [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."77- [readme] results<-rMSIcleanup::annotate_matrix(pks,"Ag1",full); rMSIcleanup::generate_pdf_report(results,pks,full,"test",folder="/home/gbaquer/"): "results<-rMSIcleanup::annotate_matrix(pks,"Ag1",full); rMSIcleanup::generate_pdf_report(results,pks,full,"test",folder="/home/gbaquer/")"
HolobiomicsLab