# Metabolite Peak Annotation

> Use when after peak detection has identified significant m/z and retention time features in untargeted or targeted mass spectrometry data (as a .raw, .d, or mzXML file).

- Skill: `holobiomicslab/metabolite-peak-annotation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/metabolite-peak-annotation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/metabolite-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/metabolite-peak-annotation

---


# metabolite-peak-annotation

## Summary

Annotation of detected metabolomics peaks by matching mass spectrometry features (m/z, retention time, intensity) against metabolite databases and reference spectra to assign chemical identities. This skill transforms a peak table into an annotated feature set suitable for downstream metabolite identification and quantification.

## When to use

After peak detection has identified significant m/z and retention time features in untargeted or targeted mass spectrometry data (as a .raw, .d, or mzXML file). Use this skill when you have a preliminary peak table with m/z values, retention times, and intensities, and need to assign putative metabolite identities to support compound identification and concentration calibration.

## When NOT to use

- Peak detection has not yet been completed; start with peak detection algorithms instead.
- Input is already a fully annotated and validated metabolite feature table; proceed directly to downstream statistical or pathway analysis.
- Mass spectrometry data quality is severely compromised (e.g., low signal-to-noise, extensive baseline drift) such that reliable peak detection cannot precede annotation.

## Inputs

- Peak table with columns: peak_id, m/z, retention_time, intensity
- Mass spectrometry data in supported formats (.raw, .d, mzXML)
- Metabolite reference database(s)
- Reference mass spectra library or spectral database

## Outputs

- Annotated peak table with columns: peak_id, m/z, retention_time, intensity, metabolite_annotation, database_identifier
- Peak annotation report with match scores and confidence metrics

## How to apply

Load the detected peak table containing m/z, retention time, and intensity values into SMART. Match each peak's m/z and retention time signature against integrated metabolite databases and reference mass spectra libraries. For each peak, select the best-scoring match (by mass accuracy and spectral similarity) and assign a metabolite annotation. Compile results into an annotated peak table that includes peak identifiers, original m/z and retention time, intensity measurements, and assigned metabolite names or database identifiers. Validate annotation quality by checking mass error tolerances (typical <5 ppm for high-resolution instruments) and spectral match scores before proceeding to post-analysis steps such as peak identification and concentration calibration.

## Related tools

- **R** (Core programming environment for executing peak annotation algorithms and database matching logic) — https://github.com/YuJenL/SMART
- **R GUI** (User-friendly graphical interface for SMART's peak annotation module, enabling interactive database selection and annotation review) — https://github.com/YuJenL/SMART

## Evaluation signals

- All detected peaks in the input peak table receive at least one annotation assignment (100% coverage).
- Mass error (observed m/z minus database reference m/z) falls within expected tolerance for the instrument type (typically <5 ppm for high-resolution MS).
- Spectral similarity scores (e.g., cosine similarity to reference spectrum) exceed a predefined threshold (e.g., >0.7), indicating high-quality matches.
- Annotated retention times are consistent with known metabolite retention indices in the experimental separation method (e.g., within ±1–2 min for reverse-phase LC).
- Annotated peak table contains no duplicate metabolite assignments for distinct peaks without justification (e.g., isobaric metabolites).

## Limitations

- Annotation quality depends on completeness and accuracy of the metabolite reference database; metabolites absent from the database remain unannotated.
- High-resolution mass accuracy (typically <5 ppm) is required for reliable m/z matching; lower-resolution instruments may produce ambiguous or incorrect annotations.
- Isobaric metabolites (same m/z, different structure) cannot be distinguished by m/z alone; retention time and reference spectra are needed to disambiguate.
- For untargeted data, annotation is semi-quantitative; concentrations require post-analysis calibration and standard curves.

## Evidence

- [intro] Peak Analysis and annotation: Implement peak analysis for both untargeted and targeted data and peak annotation.: "Peak Analysis and annotation: Implement peak analysis for both untargeted and targeted data and peak annotation."
- [other] Annotate detected peaks by matching against metabolite databases and reference spectra.: "Annotate detected peaks by matching against metabolite databases and reference spectra."
- [other] Compile results into a peak table containing peak identifiers, m/z, retention time, intensity, and assigned annotations.: "Compile results into a peak table containing peak identifiers, m/z, retention time, intensity, and assigned annotations."
- [intro] Execute peak identification and concentration calibration: "Post-analysis: Execute peak identification and concentration calibration"