/metabolomics-annotation

name: metabolomics-annotation
description: Load when matching LC-MS m/z features to an explicit local metabolite reference within a ppm
  tolerance; bundled HMDB entries are for explicit demonstrations only. Skip pathway ORA (use
  metabolomics-pathway-enrichment) and spectral matching or online searches (use external SIRIUS / GNPS).
trigger: metabolite annotation, SIRIUS, GNPS, MetFrag, spectral matching, metabolite ID, ppm tolerance
tags:
- metabolomics
- annotation
- hmdb
- demo
- mz-match

metabolomics-annotation

When to use

Match m/z to adduct masses in an explicit reference or the bundled 15-metabolite demo. Use external SIRIUS/GNPS for spectral or database-scale identification.

Use from a step

import pandas as pd
from skills._sdk.notebook import load_skill, read_input, write_output
library = load_skill("metabolomics-annotation")
data = read_input('features.csv', reader=pd.read_csv)
reference = read_input('reference.csv', reader=pd.read_csv)
result = library.annotate(data, reference=reference)
write_output(result, 'tables/result.csv')

[examples/example_step.py](examples/example_step.py) runs a seeded synthetic example through the step runner and writes a table and Figure. Computations return new DataFrames, leave the input unchanged and expose diagnostics through `run_info(result)`. Plotting functions write no files.

API

<!-- api:begin generated from _api.py; regenerate with run.py api <skill dir> --write -->

`annotate(data, *, database='hmdb', ppm=10.0, adducts=None, reference=None)`

Match every observed m/z to all reference adducts within tolerance.

:param data: Feature DataFrame with a numeric mz column. :param database: CLI default hmdb; label for the supplied reference, not a database fetch. :param ppm: CLI default 10; nonnegative mass error tolerance in parts per million. :param adducts: CLI default None resolves to [M+H]+ and [M-H]-. :param reference: Required DataFrame with name, neutral_mass, database_id and formula; demo_reference() is for demonstrations only. :returns: A new annotations DataFrame; attrs['run_info'] names the reference scope. :raises ValueError: Reference, observed masses, tolerance or adducts are invalid.

`demo_reference()`

Return the 15 bundled metabolites for explicit demonstrations.

:returns: An independent reference DataFrame marked as demo in its attrs.

`run_info(data, *, keep=True)`

Read diagnostics attached to a returned table.

:param data: DataFrame returned by this library. :param keep: Default True; use False in the CLI to remove diagnostics. :returns: An independent dictionary describing the run. :raises ValueError: The table carries no run_info.

`mass_error_figure(data)`

Plot the ppm error of matched metabolite candidates.

:param data: Annotation table returned by annotate. :returns: A matplotlib Figure. :raises KeyError: ppm_error is absent.

<!-- api:end -->

Methods and parameters

Pass `reference=` with name, neutral_mass, database_id and formula for local reference mass matching. The CLI requires `--reference-file reference.csv` for real input. No network lookup runs; `database` labels the supplied reference. `demo_reference()` explicitly selects 15 illustrative HMDB entries, also used by `--demo`.

Gotchas

• `annotate` rejects missing reference data; demo references cannot be relabelled as another database. Each query can have multiple candidate rows in `tables/annotations.csv`; Unknown rows retain unmatched queries. Confidence labels describe ppm bins, not identification probability.
• `result.json` preserves the reference scope in `data.run_info.reference_scope`; demo matches are not biological identification evidence.

Inputs and outputs

CSV input; `tables/annotations.csv`, `report.md` and `result.json`. The CLI writes `reproducibility/commands.sh`. The function library returns objects; the CLI and step own file writes.

CLI

python skills/metabolomics/metabolomics-annotation/metabolomics_annotation.py --demo --output /tmp/metabolomics_annotation
python skills/metabolomics/metabolomics-annotation/metabolomics_annotation.py --input features.csv --reference-file reference.csv --output /tmp/metabolomics_annotation_real

See also

• [Parameters](references/parameters.md)
• [Methodology](references/methodology.md)
• [Output contract](references/output_contract.md)

Dependencies

`numpy`, `pandas`, `matplotlib`