# Accurate Mass Metabolite Search Against Hmdb

> Use when after MS1 feature detection and spectra merging in an untargeted or semi-targeted metabolomics workflow, when you have a list of observed accurate m/z values from high-resolution mass spectrometry (e.

- Skill: `holobiomicslab/accurate-mass-metabolite-search-against-hmdb` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/accurate-mass-metabolite-search-against-hmdb`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/accurate-mass-metabolite-search-against-hmdb/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/accurate-mass-metabolite-search-against-hmdb

---


# accurate-mass-metabolite-search-against-hmdb

## Summary

Search detected MS1 features against the Human Metabolome Database (HMDB) using accurate mass values and positive/negative adduct libraries to annotate unknowns in untargeted FIA-MS and full-scan metabolomics workflows. This skill bridges peak detection and compound identification by matching observed m/z values to putative metabolite structures.

## When to use

After MS1 feature detection and spectra merging in an untargeted or semi-targeted metabolomics workflow, when you have a list of observed accurate m/z values from high-resolution mass spectrometry (e.g., FIAMS FullScan data at 12000 ppm resolution) and need to assign metabolite identities prior to background filtering and adduct deconvolution.

## When NOT to use

- Input features have been pre-annotated via targeted methods (e.g., MRM transitions with known retention times); use this skill only for unknowns.
- Mass spectrometry data is low-resolution (e.g., quadrupole, nominal m/z); accurate mass search requires ≥5 ppm accuracy to distinguish isobars.
- No HMDB or curated mass library is available or accessible; the skill requires validated reference compound databases.

## Inputs

- merged MS1 feature list (mzML format or OpenMS featureXML)
- HMDB mapping files with theoretical m/z values and adduct definitions
- positive adduct library (e.g., [M+H]+, [M+Na]+, [M+K]+)
- negative adduct library (e.g., [M-H]-, [M+Cl]-)
- accurate mass tolerance threshold (ppm)

## Outputs

- annotated feature list with putative metabolite identities
- mzTab output with compound annotations and metavalues
- feature table with HMDB mapping scores and confidence ranks

## How to apply

Load the merged MS1 features and invoke SEARCH_ACCURATE_MASS against HMDB mapping files, specifying both positive and negative adduct libraries to account for ionization diversity in FIA-MS. The search compares observed m/z values to theoretical m/z values of known metabolites in HMDB, typically using mass tolerance windows appropriate to instrument resolution (e.g., ±5–10 ppm for Orbitrap-level accuracy). Annotations are stored in mzTab format alongside feature metadata (e.g., retention time, intensity) to enable downstream filtering by signal intensity thresholds and blank-to-sample ratios. The rationale is that accurate mass alone provides provisional identifications; subsequent background estimation and feature filtering steps remove false positives driven by contamination or chemical noise.

## Related tools

- **SmartPeak** (Orchestrates SEARCH_ACCURATE_MASS workflow step and manages feature annotation pipeline) — https://github.com/AutoFlowResearch/SmartPeak
- **OpenMS** (Underlying toolkit providing MS data I/O, accurate mass matching algorithms, and mzTab export)
- **pyOpenMS** (Python bindings for parsing and post-processing annotated feature files and mass mapping results)
- **BFAIR** (Companion library offering post-hoc FIA-MS annotation analysis and metabolite network visualization) — https://github.com/AutoFlowResearch/BFAIR
- **SmartPeakGUI** (Interactive visualization and validation of HMDB search results before and after background filtering) — https://github.com/AutoFlowResearch/SmartPeak

## Examples

```
# In SmartPeak workflow configuration (workflow_FIAMS_Unknowns.csv):
# Step 5: SEARCH_ACCURATE_MASS -in features.featureXML -db HMDB_mapping.tsv -mass_tolerance 5 -adducts pos_neg -out annotated_features.mzTab
```

## Evaluation signals

- Annotated feature list contains ≥1 HMDB compound per input m/z within specified tolerance; verify m/z match errors are ≤ tolerance threshold (typically ≤5 ppm).
- mzTab output includes populated compound reference columns (database ID, chemical formula, exact mass, adduct type) for ≥80% of detected features (or lower if expected in biological sample).
- Positive and negative adduct annotations are both present and distinguish chemically plausible ionization products (e.g., [M+H]+ vs. [M-H]- are not assigned to the same feature).
- Background estimation step (ESTIMATE_FEATURE_BACKGROUND_INTERFERENCES) succeeds and reduces feature count by removing low-intensity matches present in blank samples, confirming provisional identities are real signals.
- Downstream adduct merging (MERGE_FEATURES) clusters multiple adduct annotations of the same compound, indicating mass search correctly resolved structural isomers or different ionization states.

## Limitations

- Accurate mass search is ambiguous for isomeric metabolites with identical m/z; chemical identity requires orthogonal evidence (e.g., retention time, MS/MS fragmentation, or NMR).
- HMDB coverage is incomplete for lipids, unusual phytochemicals, and microbial metabolites; annotations for out-of-database compounds will be false negatives.
- Adduct ionization efficiency varies by matrix and instrument; the positive/negative libraries may not cover all observable adducts in a given sample, leading to missed identifications or misassignments.
- No changelog or version history provided for HMDB mapping files; reproducibility may be compromised if library versions are not explicitly tracked.
- Mass tolerance must be tuned to instrument calibration; poorly calibrated instruments or drifting m/z offsets can cause systematic search failures or false positives.

## Evidence

- [methods] Perform accurate mass search against HMDB mapping files using SEARCH_ACCURATE_MASS with positive and negative adduct libraries.: "Perform accurate mass search against HMDB mapping files using SEARCH_ACCURATE_MASS with positive and negative adduct libraries."
- [other] SmartPeak automates workflow steps from peak detection and integration over calibration curve optimization, to quality control reporting, which form the basis for configuring analysis types such as FIAMS FullScan Unknowns.: "SmartPeak automates workflow steps from peak detection and integration over calibration curve optimization, to quality control reporting, which form the basis for configuring analysis types such as"
- [other] Extract spectra windows over the acquisition time range (0–30 min) using EXTRACT_SPECTRA_WINDOWS with FIAMS resolution set to 12000 and max_mz to 1500.: "Extract spectra windows over the acquisition time range (0–30 min) using EXTRACT_SPECTRA_WINDOWS with FIAMS resolution set to 12000 and max_mz to 1500."
- [other] Store mzTab annotations with STORE_ANNOTATIONS and feature lists with STORE_FEATURES.: "Store mzTab annotations with STORE_ANNOTATIONS and feature lists with STORE_FEATURES."
- [readme] The software is based on the OpenMS toolkit.: "The software is based on the OpenMS toolkit."