metabolomics-pathway-enrichment

metabolomics-pathway-enrichment

When to use

Run metabolite-name ORA against explicit pathways or nine demo pathways. External mummichog/FELLA are required for their own methods.

Use from a step

import pandas as pd
import json
from pathlib import Path
from skills._sdk.notebook import load_skill, read_input, write_output
library = load_skill("metabolomics-pathway-enrichment")
data = read_input('features.csv', reader=pd.read_csv)
pathways = read_input('pathways.json', reader=lambda path: json.loads(Path(path).read_text()))
result = library.enrich(data['metabolite'], pathways=pathways)
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 -->

enrich(data, *, method='ora', pathways=None)

Test case-insensitive exact metabolite-name overlap by hypergeometric ORA.

:param data: Iterable of metabolite names; duplicates count once in each overlap. :param method: CLI default ora, the only implemented method. :param pathways: Required mapping of pathway names to metabolites lists and kegg_id labels; use demo_pathways() only for demonstrations. :returns: A new table; BH FDR covers pathways with at least one hit, matching the CLI. :raises ValueError: A requested method is unimplemented or reference is empty.

demo_pathways()

Return an independent copy of the nine illustrative pathway sets.

:returns: A mapping for explicit demo use, not a complete pathway database.

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.

enrichment_figure(data, *, n_top=10)

Plot the strongest pathway overlaps by adjusted p value.

:param data: Results returned by enrich. :param n_top: Default 10; maximum number of pathways shown. :returns: A matplotlib Figure. :raises KeyError: pathway or fdr is absent.

<!-- api:end -->

Methods and parameters

Matching is case-insensitive exact name equality, not substring matching. The background is the union of reference members. Hypergeometric survival probabilities and BH correction apply to pathways with at least one hit, matching the legacy CLI.

Gotchas

• enrich requires explicit pathways= and implements only ora. Missing reference data and fella/mummichog requests fail. demo_pathways() explicitly selects the nine illustrative sets; never use these as biological evidence.
• tables/pathway_enrichment.csv has a stable schema even with no overlap. result.json records the reference scope in data.run_info.reference_scope.

Inputs and outputs

CSV input; tables/pathway_enrichment.csv, report.md and result.json. Demo mode also writes its synthetic input CSV at the output root. Real input also requires a JSON reference: {"pathway name": {"kegg_id": "identifier", "metabolites": ["glucose", "pyruvate"]}}. The function library returns objects; the CLI and step own file writes.

CLI

python skills/metabolomics/metabolomics-pathway-enrichment/met_pathway.py --demo --output /tmp/metabolomics_pathway_enrichment
python skills/metabolomics/metabolomics-pathway-enrichment/met_pathway.py --input features.csv --pathway-file pathways.json --output /tmp/metabolomics_pathway_real

See also

• Parameters
• Methodology
• Output contract

Dependencies

numpy, pandas, scipy, matplotlib