Metabolite Identifier Mapping

Metabolite Identifier Mapping

Summary

Maps detected molecular features to metabolite identifiers and structural metadata by executing accurate mass searches against a reference database (e.g., HMDB) using configured mass error tolerances and adduct ion specifications. This skill bridges peak detection and metabolite annotation in untargeted FIA-MS workflows.

When to use

After peak detection and MS1 feature picking from merged FIA-MS spectra (typically 0–30 s acquisition window), when you have a list of accurate monoisotopic masses and need to assign HMDB compound identifiers, molecular formulas, and structural annotations to support mzTab output generation or untargeted metabolomics interpretation.

When NOT to use

• Input is already a fully annotated feature table with verified metabolite identifiers; re-mapping risks introducing conflicting or redundant annotations.
• Mass calibration error exceeds the configured tolerance window; feature masses are unreliable and will produce false or spurious matches.
• Reference database mapping files are missing, outdated, or incompatible with the ion adduct specifications; the search will fail or return incomplete annotations.

Inputs

• Merged MS1 spectra (mzML or OpenMS native format) with detected molecular features and accurate m/z values
• Feature list with monoisotopic masses and integration metadata from peak picking
• HMDB reference database mapping files (HMDBMappingFile.tsv, HMDB2StructMapping.tsv)
• Ion adduct specification files (positive_adducts.tsv, negative_adducts.tsv)
• Mass error tolerance threshold (ppm)

Outputs

• Annotated feature list with HMDB compound identifiers and molecular formula assignments
• mzTab format file summarizing accurate mass search annotations and feature lists
• Metabolite-to-feature mapping table (typically embedded in mzTab PSM and MTD sections)

How to apply

Execute accurate mass search against the reference database (HMDB) using the detected feature masses and the configured mass error tolerance (typically in ppm range specified in SmartPeak parameters). Supply positive and negative adduct mapping files (e.g., positive_adducts.tsv, negative_adducts.tsv) and HMDB structure mapping files (HMDBMappingFile.tsv, HMDB2StructMapping.tsv) to enable ionization-aware and structure-aware annotation. The search returns one or more candidate matches per feature; annotate each detected peak with the matched HMDB compound identifier, molecular formula, and associated structural metadata. Assemble the annotated features into mzTab format, preserving the mass-to-metabolite linkage for downstream reporting and validation.

Related tools

• SmartPeak (Orchestrates the complete workflow including peak detection, accurate mass search against HMDB, and annotation assembly into mzTab format) — https://github.com/AutoFlowResearch/SmartPeak
• SmartPeakCLI (Command-line interface for executing accurate mass search and annotation steps without GUI interaction) — https://github.com/AutoFlowResearch/SmartPeak
• OpenMS (Underlying toolkit providing accurate mass search algorithms and mzTab export functionality)
• pyOpenMS (Python bindings for parsing and programmatically processing mzTab and annotation output files)

Examples

docker run --rm -ti -v C:/data:/sample-data autoflowresearch/smartpeak-cli:latest bash -c "SmartPeakCLI --input_raw /sample-data/FIAMS_data.mzML --accuracy_mass_search --hmdb_mapping /sample-data/HMDBMappingFile.tsv --output_mtab /sample-data/output.mzTab"

Evaluation signals

• All detected features have assigned HMDB compound identifiers and molecular formulas; no features remain unannotated unless outside database coverage.
• Mass error between detected m/z and reference m/z is within the configured tolerance for all matched features (verify in mzTab accuracy metric columns).
• Ion adduct assignments are consistent with the specified positive/negative adduct lists; check PSM columns in mzTab for adduct type annotations.
• mzTab output file validates against the mzTab schema (v1.0 or later); verify MTD (metadata), PSM (peptide spectrum match analog), and feature sections are present and non-empty.
• Mapping reproducibility: re-running the workflow with identical parameters and input files produces identical HMDB assignments and mzTab output.

Limitations

• Reference database coverage is incomplete; many detected features may fall outside HMDB scope and remain unmapped.
• Isotopic variants and in-source fragments can produce ambiguous mass matches; the skill does not resolve multiplicity without additional MS/MS confirmation.
• Mass calibration drift across the acquisition window (0–30 s) can degrade accuracy; pre-calibration using SmartPeak's calibration curve optimization is required.
• Adduct specification files must be manually curated and kept synchronized with the ionization mode and instrument configuration; mismatches produce incorrect annotations.

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."
• [other] SmartPeak automates all steps from peak detection and integration over calibration curve optimization, to quality control reporting, which collectively support the generation of comprehensive data summaries including feature annotations and quality metrics.: "SmartPeak automates all steps from peak detection and integration over calibration curve optimization, to quality control reporting, which collectively support the generation of comprehensive data"