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."
1---2name: accurate-mass-metabolite-search-against-hmdb3description: 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.4license: CC-BY-4.05---67# accurate-mass-metabolite-search-against-hmdb89## Summary1011Search 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.1213## When to use1415After 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.1617## When NOT to use1819- Input features have been pre-annotated via targeted methods (e.g., MRM transitions with known retention times); use this skill only for unknowns.20- Mass spectrometry data is low-resolution (e.g., quadrupole, nominal m/z); accurate mass search requires ≥5 ppm accuracy to distinguish isobars.21- No HMDB or curated mass library is available or accessible; the skill requires validated reference compound databases.2223## Inputs2425- merged MS1 feature list (mzML format or OpenMS featureXML)26- HMDB mapping files with theoretical m/z values and adduct definitions27- positive adduct library (e.g., [M+H]+, [M+Na]+, [M+K]+)28- negative adduct library (e.g., [M-H]-, [M+Cl]-)29- accurate mass tolerance threshold (ppm)3031## Outputs3233- annotated feature list with putative metabolite identities34- mzTab output with compound annotations and metavalues35- feature table with HMDB mapping scores and confidence ranks3637## How to apply3839Load 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.4041## Related tools4243- **SmartPeak** (Orchestrates SEARCH_ACCURATE_MASS workflow step and manages feature annotation pipeline) — https://github.com/AutoFlowResearch/SmartPeak44- **OpenMS** (Underlying toolkit providing MS data I/O, accurate mass matching algorithms, and mzTab export)45- **pyOpenMS** (Python bindings for parsing and post-processing annotated feature files and mass mapping results)46- **BFAIR** (Companion library offering post-hoc FIA-MS annotation analysis and metabolite network visualization) — https://github.com/AutoFlowResearch/BFAIR47- **SmartPeakGUI** (Interactive visualization and validation of HMDB search results before and after background filtering) — https://github.com/AutoFlowResearch/SmartPeak4849## Examples5051```52# In SmartPeak workflow configuration (workflow_FIAMS_Unknowns.csv):53# Step 5: SEARCH_ACCURATE_MASS -in features.featureXML -db HMDB_mapping.tsv -mass_tolerance 5 -adducts pos_neg -out annotated_features.mzTab54```5556## Evaluation signals5758- 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).59- 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).60- 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).61- 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.62- Downstream adduct merging (MERGE_FEATURES) clusters multiple adduct annotations of the same compound, indicating mass search correctly resolved structural isomers or different ionization states.6364## Limitations6566- 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).67- HMDB coverage is incomplete for lipids, unusual phytochemicals, and microbial metabolites; annotations for out-of-database compounds will be false negatives.68- 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.69- No changelog or version history provided for HMDB mapping files; reproducibility may be compromised if library versions are not explicitly tracked.70- Mass tolerance must be tuned to instrument calibration; poorly calibrated instruments or drifting m/z offsets can cause systematic search failures or false positives.7172## Evidence7374- [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."75- [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"76- [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."77- [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."78- [readme] The software is based on the OpenMS toolkit.: "The software is based on the OpenMS toolkit."
HolobiomicsLab