metabolomics-peak-detection

name	metabolomics-peak-detection
description	Load when running per-sample peak picking on a feature × intensity table via `scipy.signal.find_peaks` — emits per-(sample, feature) detected peaks with prominence and width. Skip when working with mz / RT raw scans (use `metabolomics-xcms-preprocessing` upstream) or when only normalising / quantifying (use `metabolomics-quantification`).
version	0.5.0
author	OmicsClaw
license	MIT
tags	["metabolomics","peak-detection","find-peaks","xcms","mzmine"]
requires	["pandas","numpy","scipy"]

metabolomics-peak-detection

When to use

The user has a feature × sample intensity matrix (output of metabolomics-xcms-preprocessing or any feature-level table) and wants per-sample peaks detected via scipy.signal.find_peaks with configurable prominence / height / distance. Sample columns are auto-detected by name (sample* or *intensity*); override with --sample-prefix <prefix>.

For raw LC-MS preprocessing use metabolomics-xcms-preprocessing. For normalisation use metabolomics-normalization.

Inputs & Outputs

Input	Format	Required
Feature × intensity table	.csv with intensity columns starting sample or containing intensity (case-insensitive)	yes (unless --demo)
Sample column override	--sample-prefix <str>	no
Detection params	--prominence <float> (default 1e4), --height <float> (default None), --distance <int> (default 5)	no

Output	Path	Notes
Detected peaks	tables/detected_peaks.csv	per-(sample, feature) peak with prominence + width
Report	report.md + result.json	n_samples, mean_prominence

Flow

1. Load CSV (--input <feature_intensity.csv>) or generate a demo at output_dir/*.csv (peak_detect.py:281).
2. Auto-detect sample columns: if --sample-prefix is set, use c.startswith(prefix) (peak_detect.py:294); else fall back to "intensity" in c.lower() or c.lower().startswith("sample") (:126).
3. Per sample column, run scipy.signal.find_peaks with prominence=, height=, distance=.
4. Write tables/detected_peaks.csv (peak_detect.py:306) + report.md + result.json.

Gotchas

• Sample-column auto-detection is CASE-INSENSITIVE substring match. peak_detect.py:126 uses "intensity" in c.lower() or c.lower().startswith("sample"). Columns like Intensity_1, sample_a, SAMPLE.5 all match; columns like signal_1 or abundance do NOT — pre-rename or use --sample-prefix signal.
• No sample columns ⇒ ValueError. peak_detect.py:130 raises ValueError("...") when neither auto-detection nor --sample-prefix matches any column.
• --input REQUIRED unless --demo. peak_detect.py:285 raises ValueError("--input required when not using --demo").
• --prominence default 1e4 is intensity-unit-dependent. Suitable for raw counts at 1e4-1e6 magnitude; for log-transformed data, set --prominence 0.5 or smaller. Wrong threshold silently yields zero peaks.
• --distance is in INDEX UNITS (sample order), not seconds. peak_detect.py:270 notes default=5 — meaning at-least-5-row separation between adjacent peaks. If your features are RT-sorted, this corresponds to ~5 RT bins; if shuffled, the constraint is meaningless.
• NaN values are silently treated as 0 by find_peaks. Pre-impute or filter NaN rows if they affect detection.

Key CLI

# Demo
python omicsclaw.py run metabolomics-peak-detection --demo --output /tmp/peak_demo

# Real intensity matrix (auto-detect sample columns)
python omicsclaw.py run metabolomics-peak-detection \
  --input feature_intensities.csv --output results/ \
  --prominence 1e5 --distance 3

# Custom sample-column prefix
python omicsclaw.py run metabolomics-peak-detection \
  --input my_table.csv --output results/ --sample-prefix replicate_

See also

• references/parameters.md — every CLI flag
• references/methodology.md — scipy.signal.find_peaks semantics, prominence vs height
• references/output_contract.md — tables/detected_peaks.csv schema
• Adjacent skills: metabolomics-xcms-preprocessing (upstream — converts raw LC-MS to feature × sample matrix), metabolomics-quantification (parallel — impute + normalise), metabolomics-annotation (downstream — annotate features against databases), metabolomics-normalization (downstream — log / median / quantile)