Spectral annotation and overlay visualization

Skill HolobiomicsLab/asb-skill-collections/packs/metabolomics/ms-imaging/skills/spectral-annotation-and-overlay-visualization

Curated, evidence-grounded skill and software-tool collections for scientific AI agents, generated by the AgenticScienceBuilder

Install

npx -y skills add HolobiomicsLab/asb-skill-collections --skill spectral-annotation-and-overlay-visualization

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

14 stars14 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when after correlation testing has validated putative parent–adduct ion pairs (e.g., via corrPairsMSI() on a massdiff object annotated with adductMatch results), use this skill to annotate and visualize the mass spectrum plot to confirm that identified pairs exhibit expected overlap—e.

The file declares its own license as CC-BY-4.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

7.6 KB, as published. Nobody here has run it

Spectral Annotation and Overlay Visualization

Summary

Annotate mass spectra with identified parent ions and adduct ions, then visualize them as overlaid scatter plots using contrasting colors and symbols to reveal spatial and spectral relationships. This skill enables discrimination of adduct-parent ion pairs in MALDI-MSI data through simultaneous visual inspection of their co-occurrence patterns.

When to use

After correlation testing has validated putative parent–adduct ion pairs (e.g., via corrPairsMSI() on a massdiff object annotated with adductMatch results), use this skill to annotate and visualize the mass spectrum plot to confirm that identified pairs exhibit expected overlap—e.g., red points (adduct ions) spatially co-localized with blue points (parent ions) in the imaging data.

When NOT to use

Massdiff object has not been correlation-tested; overlays would show spurious associations without spatial validation.
Adduct type of interest has no statistically significant ion pairs after corrPairsMSI() filtering; visualization would be uninformative.
Input msimat object is not in mass2adduct format or lacks pixel-level intensity data; pointsAdducts() requires full imaging coordinate information.

Inputs

msimat object (preprocessed MSI data matrix with mass and intensity columns)
massdiff object annotated with adductMatch() results and filtered by corrPairsMSI() p-values

Outputs

Annotated mass spectrum plot with overlaid scatter points (red for adducts, blue for parent ions)
Visual confirmation of parent–adduct ion pair co-localization

How to apply

Begin with a preprocessed msimat object and a massdiff object that has been (1) annotated with adductMatch() to identify known adduct types and (2) filtered by corrPairsMSI() correlation testing to retain only statistically significant ion pairs. Subset the annotated massdiff object to a single adduct type (e.g., subset(d.diff.annot.cor, matches=='Na adduct')). Invoke pointsAdducts() twice: first with which='adduct', signif=TRUE, pch=20, cex=0.5, col='red' to overlay adduct ion peaks as red filled circles, then with which='parent', signif=TRUE, pch=1, cex=0.5, col='blue' to overlay parent ion peaks as blue circle outlines. The resulting annotated mass spectrum plot should show red and blue point clusters that overlap, indicating ions serving dual roles (adduct and parent) or spatially correlated pairs. Success is indicated by recognizable overlap patterns consistent with the biological hypothesis that parent and adduct ions co-localize in imaging pixels.

Related tools

mass2adduct (R package providing pointsAdducts() function for annotation and overlay visualization, and msimat/massdiff object classes) — https://github.com/kbseah/mass2adduct
R (Runtime environment for executing pointsAdducts() visualization commands)

Examples

pointsAdducts(d, subset(d.diff.annot.cor, matches=='Na adduct'), which='adduct', signif=TRUE, pch=20, cex=0.5, col='red'); pointsAdducts(d, subset(d.diff.annot.cor, matches=='Na adduct'), which='parent', signif=TRUE, pch=1, cex=0.5, col='blue')

Evaluation signals

Red and blue point clusters appear at overlapping spatial coordinates on the mass spectrum plot, indicating parent–adduct ion co-localization.
The proportion of overlapping red–blue point pairs matches the expected frequency of adduct-parent relationships based on biological sample composition.
Subset filtering (e.g., matches=='Na adduct') reduces the massdiff object to only the target adduct type; pointsAdducts() renders only those pairs.
Circle outlines (parent ions, pch=1) and filled circles (adduct ions, pch=20) are visually distinct and correctly colored (red vs. blue).
No spurious isolated points appear far from overlapping clusters, confirming prior corrPairsMSI() significance filtering removed uncorrelated pairs.

Limitations

pointsAdducts() is effective only when the msimat object retains full pixel-level spatial information; pre-aggregated or low-resolution spectral matrices will obscure spatial overlap patterns.
Visualization quality depends on prior correlation testing with appropriate p-value thresholds (default Bonferroni-corrected p < 0.05); looser cutoffs may introduce false-positive overlays.
Overlapping red and blue points do not confirm chemical causality; they indicate spatial co-localization only. Further validation (e.g., MS/MS fragmentation, metabolite identity) is required to confirm adduct formation.
For very large ion pair datasets, overlaid scatter plots become visually congested; filtering to top-ranked adduct types (via topAdducts()) may improve clarity.

Evidence

[other] The pointsAdducts() function generates a scatter plot that highlights adduct ions in red and parent ions in contrasting colors, enabling visual identification of the red/blue overlap pattern between sodium adducts and their corresponding parent ions.: "The pointsAdducts() function generates a scatter plot that highlights adduct ions in red and parent ions in contrasting colors, enabling visual identification of the red/blue overlap pattern between"
[other] Invoke pointsAdducts() with which='adduct', signif=TRUE, pch=20, cex=0.5, col='red' to overlay adduct ion peaks in red. Invoke pointsAdducts() again with which='parent', signif=TRUE, pch=1, cex=0.5, col='blue' to overlay parent ion peaks as blue circle outlines.: "Invoke pointsAdducts() with which='adduct', signif=TRUE, pch=20, cex=0.5, col='red' to overlay adduct ion peaks in red. Invoke pointsAdducts() again with which='parent', signif=TRUE, pch=1, cex=0.5,"
[readme] Test for spatial correlations between mass peaks in MS imaging data (imported with the msimat function). For example, we wish to see if what we believe to be pairs of parent- and derivative-ion masses tend to occur together.: "Test for spatial correlations between mass peaks in MS imaging data (imported with the msimat function). For example, we wish to see if what we believe to be pairs of parent- and derivative-ion"
[other] You can annotate the original mass spectrum using a massdiff object, to mark peaks corresponding to parent ions and adduct ions in different colors.: "You can annotate the original mass spectrum using a massdiff object, to mark peaks corresponding to parent ions and adduct ions in different colors."