metabolomics-normalization

metabolomics-normalization

When to use

The user has a feature × sample metabolomics intensity table and wants normalisation only (no imputation). Five methods:

• median (default) — divide each sample by its median.
• quantile — quantile normalisation across samples.
• total — divide by per-sample total (TIC).
• pqn — Probabilistic Quotient Normalisation (Dieterle 2006).
• log — log2(x+1) per-cell.

For combined imputation + normalisation use metabolomics-quantification.

Inputs & Outputs

Inputs

• File types: .csv
• Accepts artifact metabolomics.peak_table (csv)

Outputs

• tables/normalized.csv
• report.md
• result.json
• Produces artifact metabolomics.feature_matrix as tables/normalized.csv (csv)

Flow

1. Load CSV (--input <features.csv>) or generate a demo (--demo).
2. Dispatch on --method; reject unknown via ValueError("Unknown method: {method}. Choose from {SUPPORTED_METHODS}") at metabolomics_normalization.py:151.
3. Apply the chosen normalisation; write tables/normalized.csv (metabolomics_normalization.py:258) + report.md + result.json.

Gotchas

• --method choices are exact: median / quantile / total / pqn / log. metabolomics_normalization.py:36 defines SUPPORTED_METHODS. Aliases like tic (= total) are NOT accepted — pass total explicitly. (Note: sibling metabolomics-quantification accepts tic as a normalize choice; the two skills' vocabularies differ.)
• --input REQUIRED unless --demo. metabolomics_normalization.py:248 raises ValueError("--input required when not using --demo").
• pqn requires non-zero reference values. Probabilistic Quotient Normalisation divides by per-feature reference (median sample); features with all zeros yield NaN quotients. Pre-filter zero-prevalent features.
• log is log2(x+1). Negative values raise / propagate NaN. Pre-clip upstream.
• No imputation is performed. NaN values pass through normalisation untouched (most methods skipna; quantile may NaN-propagate). Pre-impute with metabolomics-quantification if NaNs are problematic.
• Method-specific behaviour with NaN may differ. median / total use np.nanmedian / np.nansum; quantile may collapse rows with NaN; pqn expects all-numeric.