MetaboMatch

Match metabolomics compound names against the HMDB database and annotate them with accession IDs, molecular formulas, and InChIKeys — ready for downstream multi-omics network analysis.

Works in any Python environment: scripts, Jupyter notebooks, or from the command line.

About MetaboMatch

MetaboMatch is a Python package and command-line interface (CLI) tool designed to match metabolomics compound names against the Human Metabolome Database (HMDB).

It takes metabolomics tables (such as exports from Thermo Compound Discoverer or generic CSV/XLSX files) and annotates them with HMDB accession IDs, canonical names, molecular formulas, and InChIKeys. This provides a streamlined way to prepare metabolomics data for downstream multi-omics network analysis.

The tool employs a tiered matching strategy to maximize annotation rates:

-Raw Exact: Case-insensitive exact string matching against HMDB canonical names and synonyms.

-Normalized Fuzzy: Leverages the RapidFuzz algorithm (token_set_ratio) to score similarities for names that miss an exact match.

-Semantic Search (Optional): Uses Hugging Face sentence embeddings to match compounds by structural/semantic meaning rather than mere character similarities.

---

Install

git clone https://github.com/your-username/MetaboMatch.git
cd MetaboMatch
pip install .

That's it. The package is now importable as metabomatch and the metabomatch CLI is available.

Optional extras:

# For .xls files (older Excel format)
pip install ".[xls]"

# For semantic search (see below)
pip install ".[semantic]"

---

Get the HMDB database

Download the metabolite XML directly from HMDB — no account needed:

https://hmdb.ca/system/downloads/current/hmdb_metabolites.zip

• Download the .zip — do not unzip it. The package streams directly from the zip.
• The file is ~1–2 GB. Re-download it whenever you want a fresh HMDB version; there is no bundled copy in this repo.

---

Quick start

In a script or Jupyter notebook

from metabomatch import MatchConfig, run

cfg = MatchConfig(
    input_path="serum_metabolomics.xlsx",   # .xlsx, .xls, .csv, or .tsv
    hmdb_path="hmdb_metabolites.zip",       # the zip you downloaded from HMDB
    output_path="hmdb_annotated.xlsx",      # .xlsx (also writes a .tsv) or .csv
    score_cutoff=80,                        # min fuzzy score 0–100
    top_n=3,                                # HMDB candidates kept per compound
)

run(cfg)

From the command line

metabomatch \
  --input  serum_metabolomics.xlsx \
  --hmdb   hmdb_metabolites.zip \
  --output hmdb_annotated.xlsx \
  --score  80 \
  --top    3

Run metabomatch --help for all options.

---

Input formats

Format	Notes
.xlsx / .xlsm	Thermo Compound Discoverer layout auto-detected; any other table also works
.xls	Requires pip install ".[xls]"
.csv / .tsv	Any delimiter; pandas sniffs it automatically

If your compound-name column is not named Name, set it explicitly:

cfg = MatchConfig(..., name_column="Compound")   # by header name
cfg = MatchConfig(..., name_column=2)            # by 0-based column index

---

Output columns

Every original input column is preserved. These annotation columns are appended:

Column	Description
Normalised_Name	Name after Greek→ASCII, stereo-stripping, lowercasing
Match_Status	exact / high_confidence / probable / low_confidence / no_match / unnamed / catalog_code / semantic_candidate
Match_Method	raw_exact / norm_exact / norm_fuzzy / semantic
HMDB_Accession_1..N	HMDB accession ID
HMDB_Name_1..N	HMDB canonical name
HMDB_Formula_1..N	Molecular formula
HMDB_InChIKey_1..N	InChIKey
Match_Score_1..N	0–100 fuzzy score (or 0–1 cosine similarity for semantic)

---

Matching strategy

Passes run in order; a later pass only runs if no perfect hit was found yet.

1. Raw exact — case-insensitive match against all HMDB names and synonyms
2. Norm exact — Greek letters → ASCII, stereo descriptors stripped, L-/D- prefixes handled
3. Norm fuzzy — RapidFuzz token_set_ratio above score_cutoff
4. Semantic (optional) — sentence-embedding cosine similarity, only for rows where 1–3 found nothing

---

Semantic search (optional)

Semantic search uses sentence embeddings to match by meaning rather than character similarity — useful when a trivial name and a systematic name share no substrings.

Model: sentence-transformers/all-MiniLM-L6-v2

• Free and publicly available on Hugging Face — no license restrictions
• Downloaded automatically on first use (~80 MB)

Install the extra dependencies first:

pip install ".[semantic]"

Get a free Hugging Face token (recommended to avoid download rate limits):

1. Create a free account at huggingface.co
2. Go to Settings → Access Tokens → New token (read-only is enough)
3. Set it in your environment before running:

# Linux / macOS / Jupyter terminal
export HUGGING_FACE_HUB_TOKEN=hf_your_token_here

# Windows PowerShell
$env:HUGGING_FACE_HUB_TOKEN = "hf_your_token_here"

Or in a notebook cell before importing:

import os
os.environ["HUGGING_FACE_HUB_TOKEN"] = "hf_your_token_here"

Enable in code:

cfg = MatchConfig(
    input_path="serum_metabolomics.xlsx",
    hmdb_path="hmdb_metabolites.zip",
    output_path="hmdb_annotated.xlsx",
    use_semantic=True,
    semantic_score_cutoff=0.55,   # cosine similarity 0–1; raise for stricter results
    semantic_top_n=1,
)
run(cfg)

Enable from CLI:

metabomatch --input data.xlsx --hmdb hmdb_metabolites.zip --semantic

Important: Semantic hits are tagged Match_Status = semantic_candidate and Match_Method = semantic. They are not merged into exact/probable. General-purpose embeddings cannot reliably distinguish stereoisomers (D-/L-, R/S) or close homologues — always review these rows manually before using the accession IDs downstream.

---

Requirements

• Python 3.9+
• openpyxl, rapidfuzz, lxml, tqdm, pandas (installed automatically)
• Optional: xlrd (.xls files), sentence-transformers + torch (semantic search)