---
title: Metabolomics on the platform
description: >-
  Metabolomics data preprocessing, metabolite annotation, differential analysis,
  and pathway enrichment tools for mass spectrometry workflows.
tags:
  - metabolomics
---

Metabolomics takes mass-spectrometry peak tables through a four-stage pipeline — preprocessing, metabolite annotation, differential analysis, and pathway enrichment — to tell you which small molecules change between conditions and which metabolic pathways they implicate. Reach for it when your readout is metabolites rather than genes or proteins, such as comparing treated versus control samples or finding dysregulated metabolic processes. It maps onto the same KEGG and Reactome pathways that the [genomics](/docs/genomics) toolkit queries at the gene level, giving you a metabolite-side view of the same biology. See [what you can achieve](/docs/capabilities#genomics-and-omics) for the full set.

## Metabolomics overview

The Metabolomics toolkit provides a four-stage pipeline for mass spectrometry metabolomics data: preprocessing, annotation, differential analysis, and pathway enrichment. Each stage can be run independently or chained together for end-to-end analysis.

## Architecture

```
User Data (raw mzML/mzXML, or a peak table CSV/TSV)
  --> Intent Detection
       |- Data preprocessing --> metabolomics_preprocess
       |    (peak detection and alignment via XCMS, MZmine, or OpenMS)
       |- Metabolite annotation --> metabolomics_annotate
       |    (m/z mass matching against HMDB, LipidMaps, or KEGG)
       |- Differential analysis --> metabolomics_differential
       |    (two-group contrast, fold change, statistical testing)
       +- Pathway enrichment --> metabolomics_pathway
            (KEGG enrichment or topology analysis)
  --> Async Modal Compute (2-30 min depending on stage)
  --> Structured Results with Visualizations
```

## Tool inventory

### Preprocessing

| Tool | Name | Description |
|------|------|-------------|
| Metabolomics Preprocess | `metabolomics_preprocess` | Peak detection, chromatographic alignment, and gap-filling on raw LC-MS data (mzML/mzXML) into a feature table |

Preprocessing software is selectable via `method` (`xcms`, `mzmine`, or `openms`; default XCMS), with a configurable mass accuracy tolerance in ppm and an ionization `polarity` (positive/negative).

### Annotation

| Tool | Name | Description | Data Sources |
|------|------|-------------|--------------|
| Metabolomics Annotate | `metabolomics_annotate` | Metabolite identification from a feature table by mass matching | HMDB, LipidMaps, KEGG |

Annotation matches feature m/z values against the selected database(s) (`databases`: `hmdb`, `lipidmaps`, `kegg`, or `all`) within a configurable `mass_tolerance_ppm`, with an optional list of `adducts` to consider. Matches are putative mass matches, not MS/MS-confirmed identifications — there is no MSI confidence tiering.

### Differential analysis

| Tool | Name | Description |
|------|------|-------------|
| Metabolomics Differential | `metabolomics_differential` | Statistical comparison of metabolite abundances between two sample groups |

Supports Welch's t-test, limma, or Wilcoxon (`method`, default `limma`) for a two-group `contrast` (e.g., `"treated_vs_control"`) resolved against your sample metadata. Multiple testing correction is Benjamini-Hochberg (FDR). Results include fold changes, p-values, and adjusted p-values.

### Pathway enrichment

| Tool | Name | Description | Data Sources |
|------|------|-------------|--------------|
| Metabolomics Pathway | `metabolomics_pathway` | Metabolic pathway enrichment analysis against KEGG | KEGG |

Supports `enrichment` or `topology` analysis (`analysis_type`, default `enrichment`) against KEGG metabolic pathways. Input metabolites can be HMDB, KEGG, or PubChem identifiers (`id_type`, default `hmdb`). Organism is limited to human (`hsa`) or mouse (`mmu`).

## Capabilities

### Data preprocessing

Preprocessing turns a raw LC-MS run into an analysis-ready feature table: peak detection, chromatographic alignment, and gap-filling, run through XCMS, MZmine, or OpenMS. Choose the software with `method` and set a mass accuracy tolerance in ppm.

### Metabolite identification

Annotation matches a feature table's m/z values against HMDB, LipidMaps, or KEGG within a configurable ppm tolerance, optionally restricted to a given set of adducts. Matches are putative — ranked by mass accuracy, not by MS/MS spectral confirmation.

### Statistical analysis

Differential analysis compares metabolite abundances between two groups (e.g., treated vs. control) defined by a `contrast` string. Choose the test with `method` (Welch's t-test, limma, or Wilcoxon). Results include fold changes, raw p-values, and Benjamini-Hochberg-adjusted p-values.

### Pathway mapping

Pathway enrichment maps a list of metabolite identifiers onto KEGG metabolic pathways to identify dysregulated biological processes. Choose `enrichment` (over-representation) or `topology`-based analysis via `analysis_type`.

## When to use each tool

| I want to... | Use this tool |
|--------------|---------------|
| Process a raw LC-MS run into a feature table | `metabolomics_preprocess` |
| Identify metabolites from mass spectra | `metabolomics_annotate` |
| Compare metabolite levels between groups | `metabolomics_differential` |
| Find enriched metabolic pathways | `metabolomics_pathway` |
| Run a full untargeted metabolomics pipeline | Chain all four tools |
| Get HMDB/KEGG IDs for my features | `metabolomics_annotate` |

## When to use other tools instead

| I want to... | Use this instead |
|--------------|------------------|
| Search for a specific compound by name | [PubChem](/docs/pubchem) or [ChEMBL](/docs/chembl) |
| Predict ADMET properties of a metabolite | [ADMETlab 3](/docs/admetlab3) or [ADMET-AI](/docs/admet-ai) |
| Explore KEGG pathways by name | A KEGG pathway search ([Genomics](/docs/genomics)) |
| Analyze protein expression data | [Proteomics](/docs/proteomics) |
| Look up a metabolite in literature | [PubMed](/docs/pubmed) |
| Visualize a metabolite structure | Compound Passport |

## Licensing

| Database | License |
|----------|---------|
| HMDB | Free for academic and commercial use |
| LipidMaps | CC BY 4.0 |
| KEGG | Free for academic use, commercial license available |

## Citations

> Wishart DS, et al. HMDB 5.0: the Human Metabolome Database for 2022. *Nucleic Acids Res*. 2022;50(D1):D622-D631. doi: [10.1093/nar/gkab1062](https://doi.org/10.1093/nar/gkab1062)

> Kanehisa M, Goto S. KEGG: Kyoto Encyclopedia of Genes and Genomes. *Nucleic Acids Res*. 2000;28(1):27-30. doi: [10.1093/nar/28.1.27](https://doi.org/10.1093/nar/28.1.27)

## Chat Usage

### Example Prompts

- "Preprocess my raw LC-MS mzML file with XCMS at 10 ppm mass accuracy"
- "Annotate my LC-MS features against HMDB with 5 ppm m/z tolerance"
- "Find metabolites that are significantly different between treated and control samples"
- "What metabolic pathways are enriched in my upregulated metabolites?"
- "Run differential analysis on the treated_vs_control contrast with limma"
- "Show me the pathway enrichment results for my significant HMDB metabolites"

### Workflow Chaining

- **Feeds into**: Compound Passport (drug-likeness assessment), ADMET prediction (pharmacokinetics), KEGG/Reactome pathway visualization, Literature search (metabolite-disease associations)
- **Accepts from**: Data upload (CSV/TSV peak tables), Sample metadata (group labels, batch info), Genomics tools (gene-metabolite mapping), Compound search (target metabolite identification)

## FAQ

### What mass spectrometry platforms are supported?

  The toolkit supports LC-MS and GC-MS data. Input can be provided as peak tables (CSV/TSV with m/z, retention time, and intensity columns) or as preprocessed feature matrices. Raw vendor formats (e.g., .raw, .mzML) should be converted to peak tables before upload.

### Do I need to normalize my data before annotation?

  No. When metabolomics_preprocess runs on a peak table, it applies TIC normalization and a log2 transform automatically — there is no method choice. Annotation can be run on either raw or preprocessed data.

### Which databases are used for metabolite annotation?

  The metabolomics_annotate tool matches feature m/z values against HMDB (Human Metabolome Database), LipidMaps, or KEGG, selected via the `databases` parameter (default: all three). Matching is by mass within a configurable ppm tolerance — there is no MS/MS fragmentation matching.

### Can I run pathway enrichment without differential analysis first?

  Yes. The metabolomics_pathway tool accepts a list of metabolite identifiers — HMDB, KEGG, or PubChem IDs, set via `id_type` — not free-text metabolite names. However, running differential analysis first gives you fold changes and p-values that improve enrichment interpretation.

## Read next