# Accurate Mass Database Search

> Use when after peak detection and MS1 feature extraction from FIA-MS, GC-MS, LC-MS(/MS), or CE-MS data, when you need to identify unknown metabolites by matching observed m/z values to a reference database and want to recover HMDB identifiers, molecular formulas, and structural annotations for.

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

---


# accurate-mass-database-search

## Summary

Annotate detected molecular features by searching their accurate m/z values against a curated metabolite database (HMDB) using configurable mass error tolerance and ion adduct rules. This skill produces compound identifiers, molecular formulas, and structural metadata linked to each MS1 peak.

## When to use

After peak detection and MS1 feature extraction from FIA-MS, GC-MS, LC-MS(/MS), or CE-MS data, when you need to identify unknown metabolites by matching observed m/z values to a reference database and want to recover HMDB identifiers, molecular formulas, and structural annotations for downstream quantification or pathway analysis.

## When NOT to use

- If the input data contain only MS/MS fragmentation spectra without MS1 m/z values (library matching or spectral similarity methods are more appropriate).
- If ion adduct modes are unknown or highly variable and cannot be specified in advance (ion mode determination must precede this skill).
- If the reference database is incomplete, outdated, or not curated for your biological system of interest (limiting annotation sensitivity and specificity).

## Inputs

- Detected MS1 features (m/z, retention time, peak intensity, feature ID)
- Reference metabolite database (HMDB) with mapping files (HMDBMappingFile.tsv, HMDB2StructMapping.tsv)
- Ion adduct configuration files (positive_adducts.tsv, negative_adducts.tsv)
- Mass error tolerance threshold (ppm)

## Outputs

- Annotated feature list with HMDB identifiers and compound metadata
- mzTab annotation summary file (containing feature list and mass search results)
- Match quality metrics (mass error in ppm, rank, match confidence)

## How to apply

Load detected MS1 features (m/z, retention time, intensity) and configure the accurate mass search with: (1) a reference metabolite database (HMDB with HMDBMappingFile.tsv and HMDB2StructMapping.tsv files), (2) expected ion adducts (positive_adducts.tsv, negative_adducts.tsv specifying [M+H]+, [M-H]−, [M+Na]+, etc.), and (3) mass error tolerance (typically in ppm, e.g., 5 ppm for high-resolution Orbitrap). Execute the search against the database index, matching each feature's observed m/z to theoretical m/z values of known metabolites after applying adduct mass shifts. Rank candidate matches by mass error and, optionally, by database cross-references or structural similarity. Store matched annotations (HMDB ID, compound name, molecular formula, InChI, neutral mass) as feature metadata.

## Related tools

- **SmartPeak** (Orchestrates peak detection, calibration, accurate mass search, and mzTab assembly in a unified workflow) — https://github.com/AutoFlowResearch/SmartPeak
- **SmartPeakCLI** (Command-line interface for executing accurate mass search and annotation workflows without GUI) — https://github.com/AutoFlowResearch/SmartPeak
- **OpenMS** (Underlying toolkit providing accurate mass search algorithms and m/z calibration)
- **pyOpenMS** (Python bindings for parsing and processing annotated feature files and database search results)

## Examples

```
docker run --rm -ti -v C:/data:/sample-data autoflowresearch/smartpeak-cli:latest bash -c "SmartPeakCLI --config workflow.ini --data FIAMS_FullScan_Unknowns.mzML --database HMDB_mapping --adducts positive_adducts.tsv --mz_tolerance 5 --output results.mzTab"
```

## Evaluation signals

- All detected MS1 features have a best-match HMDB entry or are explicitly marked as unannotated (no orphaned features).
- Mass errors for matched features are ≤ the specified tolerance threshold (e.g., ≤ 5 ppm for high-resolution instruments).
- Ion adduct assignments are consistent with the acquisition mode and fragmentation patterns (e.g., [M+H]+ in positive mode, [M-H]− in negative mode).
- mzTab output conforms to the mzTab specification and includes mandatory columns (feature m/z, formula, accession) and optional metadata (InChI, compound name, neutral mass).
- Reproducibility: re-running the search on the same data with the same parameters and database version yields identical annotations.

## Limitations

- Mass error tolerance must be manually configured and is instrument-dependent; misconfigration leads to false positives or missed identifications.
- HMDB is primarily human-centric; coverage of non-mammalian, environmental, or drug metabolites may be incomplete.
- Multiple structural isomers can have identical m/z values; accurate mass search alone cannot distinguish them without orthogonal data (retention time, MS/MS fragmentation, or ion mobility).
- Isotope patterns and adduct ratios are not considered in the annotation step; results may include artefactual matches for low-intensity features or co-eluting unknowns.

## Evidence

- [methods] Execute accurate mass search against the HMDB database using the mapping files (HMDBMappingFile.tsv, HMDB2StructMapping.tsv) and specified ion adducts (positive_adducts.tsv, negative_adducts.tsv) with the configured mass error tolerance.: "Execute accurate mass search against the HMDB database using the mapping files (HMDBMappingFile.tsv, HMDB2StructMapping.tsv) and specified ion adducts (positive_adducts.tsv, negative_adducts.tsv)"
- [methods] Annotate detected peaks with HMDB compound identifiers, molecular formulas, and structural metadata.: "Annotate detected peaks with HMDB compound identifiers, molecular formulas, and structural metadata."
- [methods] Assemble results into mzTab format containing the feature list and mass search annotations, then store the mzTab output file.: "Assemble results into mzTab format containing the feature list and mass search annotations, then store the mzTab output file."
- [readme] SmartPeak is an application that encapsulates advanced algorithms to enable fast, accurate, and automated processing of CE-, GC- and LC-MS(/MS) data, and HPLC data for targeted and semi-targeted metabolomics, lipidomics, and fluxomics experiments.: "SmartPeak is an application that encapsulates advanced algorithms to enable fast, accurate, and automated processing of CE-, GC- and LC-MS(/MS) data, and HPLC data for targeted and semi-targeted"