# Msi Peak Annotation

> Use when you have processed MSI data (peak matrix and spatial coordinates) from matrix-assisted laser desorption/ionization (MALDI) or silver-assisted laser desorption/ionization (AgLDI) experiments, and you need to computationally distinguish matrix ions from analyte ions before downstream feature.

- Skill: `holobiomicslab/msi-peak-annotation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/msi-peak-annotation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/msi-peak-annotation/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/msi-peak-annotation

---


# Matrix-Related Peak Annotation in Mass Spectrometry Imaging

## Summary

Automated classification of ions as matrix-related or analyte-related in MSI datasets by integrating chemical formula matching and spatial distribution coherence, with isobaric peak detection to prevent misclassification. This skill disambiguates matrix signal from biological/chemical signals in imaging mass spectrometry workflows.

## When to use

Apply this skill when you have processed MSI data (peak matrix and spatial coordinates) from matrix-assisted laser desorption/ionization (MALDI) or silver-assisted laser desorption/ionization (AgLDI) experiments, and you need to computationally distinguish matrix ions from analyte ions before downstream feature extraction, statistical analysis, or biomarker discovery. Triggered by the presence of a peak matrix file (.zip format) and associated MSI dataset (.tar format) with known or inferred matrix composition.

## When NOT to use

- Input data are already in imzML or proprietary vendor formats without prior conversion to rMSIproc format; use rMSIproc::ProcessWizard() first.
- The matrix chemical formula is unknown or ambiguous; the algorithm requires a precise formula string to match against detected peaks.
- Data do not include full spatial imaging information or are already aggregated into a feature table without per-pixel ion intensities; spatial distribution is a required input signal.

## Inputs

- Peak matrix file in rMSIproc format (.zip)
- Processed MSI imaging data in rMSI format (.tar)
- Matrix chemical formula string (e.g., 'Ag1', 'DHB', 'CHCA')
- MSI spatial coordinates (implicit in the .tar and .zip files)

## Outputs

- Annotation results object with binary matrix/non-matrix labels per ion
- Visual PDF report justifying each annotation decision
- Cleaned peak matrix with matrix-related peaks flagged or removed

## How to apply

Load the MSI peak matrix and processed imaging data into the R environment using rMSIproc and rMSI. Extract spatial distribution patterns for each detected ion across the imaging dataset. Supply the peak matrix, a chemical formula string identifying the matrix (e.g., 'Ag1' for silver), and the full imaging data object to the rMSIcleanup::annotate_matrix() function. The algorithm evaluates each ion's chemical formula against known matrix characteristics and computes spatial coherence metrics; it flags overlapped or isobaric peaks to prevent false negatives. The output is a binary classification (matrix vs. non-matrix) for each ion, justified by formula matching and spatial distribution alignment. Generate a PDF annotation report to transparently audit each classification decision before removing matrix peaks from the peak matrix.

## Related tools

- **rMSIcleanup** (Primary annotation algorithm; integrates chemical formula matching and spatial distribution analysis to classify matrix-related peaks) — https://github.com/gbaquer/rMSIcleanup
- **rMSI** (Loads and manages processed MSI imaging datasets (.tar format) to extract spatial and spectral data for annotation) — https://github.com/prafols/rMSI
- **rMSIproc** (Processes raw imzML files and manages peak matrices (.zip format) that feed into the annotation workflow) — https://github.com/prafols/rMSIproc
- **R** (Execution environment for rMSIcleanup and dependent packages)
- **devtools** (Installation and dependency management for rMSIcleanup from GitHub)

## Examples

```
results<-rMSIcleanup::annotate_matrix(pks,"Ag1",full); rMSIcleanup::generate_pdf_report(results,pks,full,"test",folder="./"); pks_clean<-rMSIcleanup::remove_matrix(pks,results)
```

## Evaluation signals

- All detected ions are assigned a binary label (matrix or non-matrix); no unclassified peaks remain in the results object.
- The PDF annotation report includes justification (formula match score and spatial coherence metric) for each ion classified as matrix-related; transparent audit trail is present.
- Isobaric and overlapped peaks are flagged and their classification confidence is reduced or flagged for manual review, indicating the overlapping peak detection feature was engaged.
- Downstream statistical analysis (e.g., PCA, univariate tests) on the cleaned peak matrix shows improved separation between sample groups or reduced noise variance compared to unannotated data.
- Visual inspection of spatial ion maps confirms that flagged matrix ions are distributed uniformly across the imaging region (consistent with matrix deposition), while retained ions show biological/chemical localization patterns.

## Limitations

- The algorithm requires a precise chemical formula string for the matrix; unknown or ambiguous matrix compositions will degrade classification accuracy.
- Overlapping peaks and isobaric ions are detected but may still be misclassified if their spatial distributions are similar; manual curation is recommended for ambiguous cases.
- Performance on novel matrix types or atypical mass ranges not represented in the training/reference set is not documented.
- The method assumes spatial imaging data are present and informative; datasets with highly heterogeneous matrix deposition or poor spatial resolution may yield unreliable annotations.

## 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"
- [readme] Install rMSI and rMSIproc via devtools, then install rMSIcleanup; load data and call annotate_matrix function: "pks<-rMSIproc::LoadPeakMatrix("[Full Path to Peak Matrix (.zip)]"); full<-rMSI::LoadMsiData("[Full Path to Processed Data (.tar)]"); results<-rMSIcleanup::annotate_matrix(pks,"Ag1",full)"
- [readme] Generate PDF report to justify annotations before removing matrix peaks: "rMSIcleanup::generate_pdf_report(results,pks,full,"test",folder="/home/gbaquer/"); pks_clean<-rMSIcleanup::remove_matrix(pks,results)"
- [readme] Process imzML using rMSIproc format before annotation: "To annotate your own data you will have to process the imzML using the following command: rMSIproc::ProcessWizard()"