# Ms Ms Spectrum Peak Annotation

> Use when you have an experimental MS/MS spectrum (e.g., from MassBank or local data) and need to identify significant fragment ions above noise, assign occurrence scores to peaks, and generate a CSV-formatted library entry for use in metabolite feature annotation pipelines.

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

---


# MS/MS Spectrum Peak Annotation

## Summary

Annotate fragment peaks in an MS/MS spectrum by applying noise and marker peak thresholds, then scoring matched ions against a metabolite library using occurrence-based scoring. This skill converts experimental spectra into library entries with scored fragment annotations suitable for downstream feature annotation in untargeted metabolomics workflows.

## When to use

You have an experimental MS/MS spectrum (e.g., from MassBank or local data) and need to identify significant fragment ions above noise, assign occurrence scores to peaks, and generate a CSV-formatted library entry for use in metabolite feature annotation pipelines. Apply this skill when building custom fragment libraries or validating fragment picks for a known metabolite with accurate m/z and adduct notation.

## When NOT to use

- Input is already a feature table or annotated library; use this skill only on raw or lightly processed MS/MS spectra.
- Spectrum is in profile (non-centroided) mode; genFragEntry requires centroid data.
- Metabolite identity, adduct type, or accurate precursor m/z are unknown or uncertain; the function requires explicit, accurate definitions to assign correct fragment annotations.

## Inputs

- Centroid-mode MS/MS spectrum (numeric intensity array indexed by m/z)
- Metabolite name (string identifier)
- Adduct notation (string, e.g., '[M+H]+')
- Accurate adduct m/z (float, monoisotopic mass)
- Output filename (string, .csv format)

## Outputs

- CSV-formatted metabolite library entry
- Annotated fragment table with columns: fragment m/z, intensity, occurrence score, match metric

## How to apply

Load the centroid-mode MS/MS spectrum and apply two cascading peak-picking filters: (1) remove signals below the noise threshold (default 0.005 relative intensity) to eliminate background noise; (2) retain only marker peaks above the mpeaksThres threshold (default 0.1) to identify significant fragments. Execute the genFragEntry function with parameters mpeaksScore=0.9 and mzTol=0.01 m/z tolerance to annotate fragment ions, compute occurrence-based match scores, and associate each peak with its mass, intensity, and scoring metric. Output the result as a CSV-formatted library entry containing the metabolite name, adduct notation (e.g., [M+H]+), accurate adduct m/z, and all scored fragments. The rationale is that dual thresholding reduces false-positive fragments (noise/minor isotopes) while preserving biologically relevant marker ions, and occurrence scoring weights peaks by their prevalence across reference spectra.

## Related tools

- **MetaboAnnotatoR** (Provides the genFragEntry function for MS/MS spectrum peak annotation and occurrence scoring; part of the broader annotation workflow for AIF LC–MS data) — https://github.com/gggraca/MetaboAnnotatoR
- **R** (Runtime environment (version 4.5.0 or higher) required to execute genFragEntry and related functions)
- **xcms** (Upstream tool for peak-picking and feature detection from raw LC-MS chromatograms in centroid mode prior to spectrum assembly)
- **RamClustR** (Companion tool for pseudo-MS/MS spectrum generation from AIF data; produces the spectral input for genFragEntry)

## Examples

```
genFragEntry(spectrum = ms2_spectrum, metabolite = 'D-Pantothenic Acid', adduct = '[M+H]+', mz_adduct = 220.1168, mpeaksThres = 0.1, mpeaksScore = 0.9, mzTol = 0.01, outfile = 'dpantothenic_acid_lib.csv')
```

## Evaluation signals

- Output CSV file is well-formed and contains columns for m/z, intensity, and occurrence score with no missing values for retained peaks.
- All retained peaks have intensity ≥ mpeaksThres (0.1) and pass the noise threshold (≥ 0.005); verify by inspecting the intensity distribution.
- Match scores are in the expected range (0–1 or 0–0.9 depending on mpeaksScore) and reflect peak occurrence frequency in reference spectra.
- Fragment annotations are chemically reasonable for the specified adduct (e.g., neutral losses, common rearrangements) and do not include peaks below noise level.
- Library entry metadata (metabolite name, adduct notation, accurate m/z) are correctly preserved and match the input specification.

## Limitations

- No changelog or version history is documented, limiting reproducibility across MetaboAnnotatoR releases.
- Threshold defaults (noise=0.005, mpeaksThres=0.1) may require optimization for different MS platforms, ionization modes, or metabolite classes; the article does not provide guidance on threshold tuning.
- Occurrence scoring depends on availability of reference spectra in the underlying database; novel metabolites or those underrepresented in public databases may receive poor scores.
- The function requires explicit, accurate metabolite name and adduct notation; errors in these inputs will propagate into library entries and cause downstream annotation failures.

## Evidence

- [intro] noise=0.005 and mpeaksThres=0.1: "Peak-picking above noise level threshold (default: 0.005) ... Peak-picking above marker peak threshold (default: 0.1)"
- [other] genFragEntry parameters and output format: "genFragEntry converts an MS/MS spectrum into a library entry by identifying marker peaks above the mpeaksThres threshold (0.1 default) and noise level (0.005 default), attributing occurrence scores"
- [intro] Centroid mode requirement: "It requires raw LC-MS AIF chromatograms acquired/transformed in centroid mode"
- [other] CSV output format: "Output results as a CSV-formatted library entry containing annotated fragments with mass, intensity, and match scores."
- [readme] MetaboAnnotatoR purpose: "This R package is designed to perform metabolite annotation of features from LC-MS All-ion fragmentation (AIF) datasets, using ion fragment databases."