Metabolomics Statistics

---
# AUTO-GENERATED header from skill.yaml — do not edit by hand.
# Edit skill.yaml, then run: python scripts/generate_skill_md.py <skill_dir>
name: metabolomics-statistics
description: Load when running univariate two-group testing (t-test / Wilcoxon / ANOVA / Kruskal-Wallis)
  on a feature × sample metabolomics CSV with `--group1-prefix` / `--group2-prefix` column matching, BH-FDR
  adjusted. Skip when working with raw spectra (use metabolomics-xcms-preprocessing); two-group DE with
  default `ctrl` / `treat` prefixes (use metabolomics-de).
version: 0.5.0
author: OmicsClaw
license: MIT
emoji: 📈
tags:
- metabolomics
- statistics
- ttest
- wilcoxon
- anova
- kruskal
- bh-fdr
requires:
- numpy
- pandas
- scipy
---

# metabolomics-statistics

## When to use

The user has a wide feature × sample CSV (rows = features as
index, columns = samples) and wants univariate two-group testing.
Four backends:

- `ttest` (default) — Welch's two-sample t-test.
- `wilcoxon` — Mann-Whitney U (non-parametric).
- `anova` — one-way ANOVA (two-group case ≡ equal-variance t-test).
- `kruskal` — Kruskal-Wallis (non-parametric ANOVA).

`--group1-prefix` / `--group2-prefix` select sample columns by
prefix; without them the script splits at column-midpoint with a
warning. Significance threshold via `--alpha` (default 0.05);
BH-FDR adjusted.

For metabolomics-DE with default `ctrl` / `treat` column prefixes
use `metabolomics-de`. For raw spectra use
`metabolomics-xcms-preprocessing`.

## Inputs & Outputs

<!-- AUTO-GENERATED from skill.yaml (interface) — do not edit by hand. Regenerate: python scripts/generate_skill_md.py <skill_dir> -->

**Inputs**

- File types: `.csv`
- Accepts artifact `metabolomics.feature_matrix` (`csv`)

**Outputs**

- `tables/statistics.csv`
- `tables/significant.csv`
- `report.md`
- `result.json`

## Flow

1. Load CSV with `pd.read_csv(args.input_path, index_col=0)` (`metabolomics_statistics.py:325`).
2. If both `--group1-prefix` and `--group2-prefix` are set, filter columns by `c.startswith(prefix)` (`metabolomics_statistics.py:330-331`); else fall back to midpoint split with a warning (`:333-340`).
3. If either group is empty, raise `ValueError("Could not determine group columns. ...")` at `:344`.
4. Dispatch on `--method` (`:209` rejects unknown with `ValueError`); per-feature test → `pvalue` + BH-adjusted `fdr`.
5. Filter `fdr < args.alpha` → `tables/significant.csv` (`:363`).
6. Write `tables/statistics.csv` (`metabolomics_statistics.py:360`) + report + result.json.

## Gotchas

- **Group prefixes are OPTIONAL with midpoint fallback.** `metabolomics_statistics.py:329-340` only honours `--group1-prefix` / `--group2-prefix` when BOTH are passed; missing one or both falls back to midpoint split (first half / second half) with a warning. Always pass BOTH for explicit group control.
- **Empty group ⇒ `ValueError`.** `metabolomics_statistics.py:344` raises if either group's column list is empty (e.g. typo in prefix). Sanity-check `--group1-prefix` / `--group2-prefix` against your column names.
- **Index column 0 is the feature ID.** `pd.read_csv(args.input_path, index_col=0)` (`:325`) is unconditional — make sure your feature-ID column is the FIRST column in the CSV.
- **`anova` = equal-variance t-test in the two-group case** (`metabolomics_statistics.py:138-140`). For more than two groups, this skill silently assumes two — extend `group_cols` lists or use a different tool for true multi-group ANOVA.
- **`wilcoxon` here is Mann-Whitney U (independent samples), NOT paired Wilcoxon signed-rank.** Don't use it for paired designs.
- **`--input` REQUIRED unless `--demo`.** `metabolomics_statistics.py:324` raises `ValueError("--input required when not using --demo")`.
- **log2FC direction depends on group order.** `group2_mean - group1_mean` convention; pass groups in the right order.

## Key CLI

```bash
# Demo
python omicsclaw.py run metabolomics-statistics --demo --output /tmp/stats_demo

# Real CSV with explicit group prefixes
python omicsclaw.py run metabolomics-statistics \
  --input features_quant.csv --output results/ \
  --method ttest --alpha 0.05 \
  --group1-prefix control_ --group2-prefix treated_

# Wilcoxon (non-parametric)
python omicsclaw.py run metabolomics-statistics \
  --input features_quant.csv --output results/ \
  --method wilcoxon --group1-prefix WT --group2-prefix KO
```

## See also

- `references/parameters.md` — every CLI flag
- `references/methodology.md` — per-method assumptions, BH FDR
- `references/output_contract.md` — `tables/statistics.csv` schema
- Adjacent skills: `metabolomics-de` (parallel — pre-set `ctrl` / `treat` prefixes), `metabolomics-quantification` (upstream — impute + normalise), `metabolomics-normalization` (upstream — normalisation only), `metabolomics-pathway-enrichment` (downstream — pathway analysis on significant features)