Step-by-step workflows for data preprocessing, metabolite annotation, differential analysis, and pathway enrichment.

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

Upload your raw data

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

Run preprocessing

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

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.

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

Adjust parameters (optional)

Re-run preprocessing with MZmine instead of XCMS

This switches the preprocessing software via the method parameter.

Workflow 2: Annotate metabolites

Start from a feature table

Annotation takes the feature table URI produced by metabolomics_preprocess.

Run annotation

Annotate my metabolomics features against HMDB with 5 ppm mass tolerance

Or configure manually:

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

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

Widen the database (optional)

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

This sets databases: "all".

Workflow 3: Differential metabolite analysis

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.

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`

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.

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)

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 for all parameters and defaults
See outputs for result field descriptions
Use KEGG for detailed pathway diagrams
Use ADMET-AI for pharmacokinetic predictions on identified metabolites

Metabolomics quickstart