metabolomics-curation

Run the four-step pipeline: parse the feature table to extract sample metadata, calculate QC metrics (CV% and biological/blank ratios), resolve duplicate annotations by composite quality score, then generate an interactive HTML report. Each step is a standalone Python script accepting Excel or CSV input.

Default FGCZ thresholds flag features with pooled QC CV% above 30% or biological/blank signal ratio below 5×. Both thresholds are adjustable via command-line arguments, with suggested values for targeted, exploratory, plasma, urine, tissue, and plant experiments.

Features sharing a compound name are ranked by a composite score weighting RT consistency (45%), low CV% (45%), and MS2 match quality (10%). The best feature is marked KEEP, near-ties are marked ALTERNATIVE for manual review, and the rest are marked REMOVE.

Yes, the generate_html_report.py script produces an equivalent self-contained HTML report using only pandas, matplotlib, and seaborn. It runs in about 10-20 seconds versus ~60 seconds for the R Markdown template and works in environments without R.

Excessive flagging usually means thresholds are too stringent for the experiment type, blanks or QC samples were misclassified in metadata.json, or overall data quality is poor. Verify sample classifications first, then relax the CV% threshold to 40% or blank ratio to 3×.

The workflow accepts Excel (.xlsx) and CSV feature tables from platforms like Compound Discoverer, XCMS, and MS-DIAL. Tables should contain Area or Norm. Area sample columns, compound identification columns, and typically 100-300 feature rows.