metabolomics-annotation

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 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
• Methodology
• Output contract

Dependencies

numpy, pandas, matplotlib