---
title: Metabolomics quickstart
description: >-
  Step-by-step workflows for data preprocessing, metabolite annotation,
  differential analysis, and pathway enrichment.
tags:
  - metabolomics
  - quickstart
---

You want to take a raw LC-MS run through to the metabolites and pathways that change between conditions; this walks the four stages — preprocess, annotate, compare, enrich — each as a step you can run alone or chain end to end.

## Metabolomics quickstart

This guide covers four common workflows: preprocessing a raw LC-MS run, annotating metabolites from a feature table, comparing metabolite levels between groups, and mapping results onto KEGG pathways.

## Workflow 1: Preprocess a raw LC-MS run

### Step 1: Upload your raw data

Upload an mzML or mzXML file through the chat interface or data panel to get a URI for it.

### Step 2: Run preprocessing

Ask Ivy in chat (or submit the job directly with `POST /api/v1/jobs`; see the [API reference](/docs/api)):

```
Preprocess my LC-MS mzML file with XCMS at 10 ppm mass accuracy
```

Ivy runs metabolomics preprocessing with the XCMS method and a 10 ppm mass tolerance.

### Step 3: Review preprocessing results

If you instead point the tool at an already-processed peak table (`peak_table_key`), it applies TIC normalization and a log2 transform and returns summary statistics:

| Field | Example Value |
|-------|---------------|
| Features detected | 4,521 |
| Samples processed | 48 |
| Normalization | TIC |
| Transformation | log2 |
| TIC median | 1,204,500 |
| Missing value rate | 0.12 |
| Mean CV | 0.34 |

### Step 4: Adjust parameters (optional)

```
Re-run preprocessing with MZmine instead of XCMS
```

This switches the preprocessing software via the `method` parameter.

## Workflow 2: Annotate metabolites

### Step 1: Start from a feature table

Annotation takes the feature table URI produced by `metabolomics_preprocess`.

### Step 2: Run annotation

```
Annotate my metabolomics features against HMDB with 5 ppm mass tolerance
```

Or configure manually:

| Parameter | Value |
|-----------|-------|
| Databases | `"hmdb"` |
| Mass tolerance | `5` ppm |

### Step 3: Review annotation results

Each feature gets a putative match or `"unknown"` — there's no multi-level confidence scale:

| Feature | Annotation | HMDB ID | Confidence |
|---------|------------|---------|-----------|
| mz_132.0773 | putative_match | HMDB0000191 | 0.5 |
| mz_146.0929 | putative_match | HMDB0000148 | 0.5 |
| mz_999.1234 | unknown | -- | 0.0 |

### Step 4: Widen the database (optional)

```
Annotate against all three databases: HMDB, LipidMaps, and KEGG
```

This sets `databases: "all"`.

## Workflow 3: Differential metabolite analysis

### Step 1: Define sample groups

Ensure your sample metadata CSV has a `group` column. Upload it to get a URI, or the tool falls back to splitting samples in half.

### Step 2: Run differential analysis

```
Find differentially abundant metabolites between treated and control groups
```

Or configure:

| Parameter | Value |
|-----------|-------|
| Contrast | `treated_vs_control` |
| Method | `limma` (default) |
| FDR threshold | `0.05` |

### Step 3: Review differential results

| Feature | log2 fold change | p-value | p-adjusted |
|---------|-------------------|---------|-----|
| mz_204.0899 | 1.23 | 1.2e-05 | 3.4e-04 |
| mz_192.0270 | -0.87 | 4.5e-04 | 0.008 |
| mz_146.0929 | 0.94 | 0.002 | 0.021 |

Only a single two-group contrast is supported per run — there is no built-in multi-group or paired-design option.

## Workflow 4: Pathway enrichment analysis

### Step 1: Prepare a metabolite list

Use the significant feature IDs from differential analysis, or your own list of HMDB, KEGG, or PubChem identifiers.

### Step 2: Run pathway enrichment

```
What KEGG pathways are enriched in my significantly upregulated metabolites?
```

Or configure:

| Parameter | Value |
|-----------|-------|
| Metabolite list | HMDB or KEGG IDs |
| Analysis type | `enrichment` (default) or `topology` |
| Organism | `hsa` (human) or `mmu` (mouse) |

### Step 3: Review enrichment results

Enrichment is tested with Fisher's exact test against a curated set of KEGG metabolic pathways:

| Pathway | Matched | Pathway size | p-value | p-adjusted |
|---------|---------|--------------|---------|-----|
| Tryptophan metabolism | 3 | 5 | 2.1e-04 | 0.006 |
| TCA cycle | 2 | 7 | 0.003 | 0.041 |

## Next steps

- See [inputs](/docs/metabolomics/inputs) for all parameters and defaults
- See [outputs](/docs/metabolomics/outputs) for result field descriptions
- Use [KEGG](/docs/genomics) for detailed pathway diagrams
- Use [ADMET-AI](/docs/admet-ai) for pharmacokinetic predictions on identified metabolites

## Read next