metabolite-feature-distribution-comparison
License: noncommercial — confirm your use is a permitted (noncommercial) purpose before applying; commercial use requires a separate license (see metadata.tool_license).
Summary
Compare distributional statistics (mean, variance, robust quantiles) of metabolic features between QC and biological sample subsets to identify discrepancies that may indicate normalization issues or sample batch effects. This skill is applied after sample partitioning and serves as a diagnostic checkpoint to ensure QC samples remain representative of biological samples during joint normalization.
When to use
When metabolomics data contains both QC control samples and biological samples that will be normalized together using methods like tGAM, rGAM, rLOESS, QC-RLSC, or QC-RSC. Apply this skill to verify that QC and biological sample distributions remain consistent; discrepancies signal that QC samples may not be representative or that batch/instrumental drift has affected one group differently.
When NOT to use
- Input data contains only QC samples or only biological samples (no comparison group exists).
- Normalization has not yet been applied—this skill is a post-normalization diagnostic, not a pre-processing filter.
- Sample type metadata is missing or unreliable; QC vs. biological classification must be accurate and complete.
Inputs
- Normalized metabolomics data matrix (rows = metabolic features, columns = samples)
- Sample metadata vector indicating QC vs. biological sample classification for each column
- Batch assignment vector (one batch label per sample, optional but recommended)
Outputs
- Discrepancy report table (CSV or data frame) with columns: feature ID, discrepancy metric value, statistical test result, affected sample count, batch(es)
- Summary statistics per feature per sample type (mean, variance, robust quantiles)
- List of flagged features exceeding discrepancy threshold
How to apply
Partition normalized metabolomics data into two subsets: QC samples (identified via sample type vector) and biological samples (all non-QC samples). For each metabolic feature, compute distributional statistics independently within each subset—use mean and variance as primary summaries, with robust quantiles (e.g., median, IQR) as complements to reduce influence of outliers. Calculate discrepancy metrics between QC and biological distributions per feature; acceptable metrics include fold-change (QC mean / biological mean), effect size (Cohen's d or similar), or distance measures (e.g., Wasserstein distance, Kolmogorov-Smirnov statistic). Apply a statistical threshold (e.g., fold-change > 1.5, effect size > 0.8, or p-value < 0.05 from a two-sample test) to flag features with significant QC–biological discrepancies. Generate and review a tabular discrepancy report listing flagged features, their discrepancy metric values, affected samples, and batch assignments; features with large discrepancies warrant investigation of instrumental drift, batch effects, or QC sample contamination before proceeding with downstream analysis.
Related tools
- Metanorm (R package implementing normalization methods (tGAM, rGAM, rLOESS, QC-RLSC, QC-RSC) with built-in QC–biological sample discrepancy checking via QCcheck parameter) — https://github.com/UGent-LIMET/Metanorm
- R (Statistical computing environment for subset partitioning, distributional statistics computation, discrepancy metric calculation, and visualization)
Examples
normdat <- metanorm(rawdata[1:5,], model = "tGAM", type = metanorm.qc, QCcheck = TRUE, batch = batch, plotdir = "~/Documents/metanormExample/")
Evaluation signals
- Discrepancy report contains no missing values; all features have discrepancy metrics and sample counts populated.
- Flagged features are reproducible across independent runs of the same data and threshold; rank order of discrepancy values is stable.
- QC and biological sample subset sizes match expected counts (sum of QC rows + sum of biological rows = total sample count).
- Fold-change, effect size, or p-value distributions are internally consistent (e.g., features with large fold-changes also show large effect sizes).
- Visual inspection of intensity-vs-order plots for flagged features reveals visible drift, batch jumps, or distributional shifts between QC and biological samples that justify flagging.
Limitations
- Discrepancy detection assumes QC samples and biological samples are drawn from comparable populations; if QC samples are intentionally spiked, enriched, or chemically distinct, systematic differences are expected and do not indicate a problem.
- Thresholds for fold-change, effect size, or p-value are heuristic and should be calibrated per metabolomics platform and study design; no universal cutoff is recommended by the source article.
- Small sample sizes (e.g., <3 QC or <3 biological samples) yield unreliable variance estimates and statistical tests; robust quantiles are preferable in such cases.
- The skill detects distributional discrepancies but does not identify root causes (instrumental drift, contamination, batch effects, or biological heterogeneity); manual inspection of pre- vs. post-normalization diagnostic plots is required to interpret findings.
Evidence
- [other] Partition dataset into QC and biological subset; compute statistics per feature per subset; calculate discrepancy metrics; apply threshold; generate report: "Partition the dataset into QC sample subset and biological sample subset. 3. Compute distributional statistics (mean, variance, or robust quantiles) for each metabolic feature within each subset. 4."
- [intro] Joint normalization with QC check is recommended; discrepancies between QC and biological samples indicate normalization issues: "We further recommend using both QC as well as biological samples for normalization, and to have metanorm check for discrepancies between QC and biological samples"
- [readme] QCcheck parameter in Metanorm enables discrepancy detection during normalization workflow: "QCcheck = TRUE, # check whether QCs are representative"
- [readme] Diagnostic plots are essential for interpreting discrepancies and assessing normalization performance: "Individual compound pre- vs. post-normalization intensity vs. order plots can be retrieved from the plotdir directory. These allow finegrained assessment of normalization performance. It is highly"
1---2name: metabolite-feature-distribution-comparison3description: Use when when metabolomics data contains both QC control samples and biological samples that will be normalized together using methods like tGAM, rGAM, rLOESS, QC-RLSC, or QC-RSC. Apply this skill to verify that QC and biological sample distributions remain consistent;4license: CC-BY-4.05---67# metabolite-feature-distribution-comparison89> **License: noncommercial** — confirm your use is a permitted (noncommercial) purpose before applying; commercial use requires a separate license (see `metadata.tool_license`). <!-- asb-license-banner -->10## Summary1112Compare distributional statistics (mean, variance, robust quantiles) of metabolic features between QC and biological sample subsets to identify discrepancies that may indicate normalization issues or sample batch effects. This skill is applied after sample partitioning and serves as a diagnostic checkpoint to ensure QC samples remain representative of biological samples during joint normalization.1314## When to use1516When metabolomics data contains both QC control samples and biological samples that will be normalized together using methods like tGAM, rGAM, rLOESS, QC-RLSC, or QC-RSC. Apply this skill to verify that QC and biological sample distributions remain consistent; discrepancies signal that QC samples may not be representative or that batch/instrumental drift has affected one group differently.1718## When NOT to use1920- Input data contains only QC samples or only biological samples (no comparison group exists).21- Normalization has not yet been applied—this skill is a post-normalization diagnostic, not a pre-processing filter.22- Sample type metadata is missing or unreliable; QC vs. biological classification must be accurate and complete.2324## Inputs2526- Normalized metabolomics data matrix (rows = metabolic features, columns = samples)27- Sample metadata vector indicating QC vs. biological sample classification for each column28- Batch assignment vector (one batch label per sample, optional but recommended)2930## Outputs3132- Discrepancy report table (CSV or data frame) with columns: feature ID, discrepancy metric value, statistical test result, affected sample count, batch(es)33- Summary statistics per feature per sample type (mean, variance, robust quantiles)34- List of flagged features exceeding discrepancy threshold3536## How to apply3738Partition normalized metabolomics data into two subsets: QC samples (identified via sample type vector) and biological samples (all non-QC samples). For each metabolic feature, compute distributional statistics independently within each subset—use mean and variance as primary summaries, with robust quantiles (e.g., median, IQR) as complements to reduce influence of outliers. Calculate discrepancy metrics between QC and biological distributions per feature; acceptable metrics include fold-change (QC mean / biological mean), effect size (Cohen's d or similar), or distance measures (e.g., Wasserstein distance, Kolmogorov-Smirnov statistic). Apply a statistical threshold (e.g., fold-change > 1.5, effect size > 0.8, or p-value < 0.05 from a two-sample test) to flag features with significant QC–biological discrepancies. Generate and review a tabular discrepancy report listing flagged features, their discrepancy metric values, affected samples, and batch assignments; features with large discrepancies warrant investigation of instrumental drift, batch effects, or QC sample contamination before proceeding with downstream analysis.3940## Related tools4142- **Metanorm** (R package implementing normalization methods (tGAM, rGAM, rLOESS, QC-RLSC, QC-RSC) with built-in QC–biological sample discrepancy checking via QCcheck parameter) — https://github.com/UGent-LIMET/Metanorm43- **R** (Statistical computing environment for subset partitioning, distributional statistics computation, discrepancy metric calculation, and visualization)4445## Examples4647```48normdat <- metanorm(rawdata[1:5,], model = "tGAM", type = metanorm.qc, QCcheck = TRUE, batch = batch, plotdir = "~/Documents/metanormExample/")49```5051## Evaluation signals5253- Discrepancy report contains no missing values; all features have discrepancy metrics and sample counts populated.54- Flagged features are reproducible across independent runs of the same data and threshold; rank order of discrepancy values is stable.55- QC and biological sample subset sizes match expected counts (sum of QC rows + sum of biological rows = total sample count).56- Fold-change, effect size, or p-value distributions are internally consistent (e.g., features with large fold-changes also show large effect sizes).57- Visual inspection of intensity-vs-order plots for flagged features reveals visible drift, batch jumps, or distributional shifts between QC and biological samples that justify flagging.5859## Limitations6061- Discrepancy detection assumes QC samples and biological samples are drawn from comparable populations; if QC samples are intentionally spiked, enriched, or chemically distinct, systematic differences are expected and do not indicate a problem.62- Thresholds for fold-change, effect size, or p-value are heuristic and should be calibrated per metabolomics platform and study design; no universal cutoff is recommended by the source article.63- Small sample sizes (e.g., <3 QC or <3 biological samples) yield unreliable variance estimates and statistical tests; robust quantiles are preferable in such cases.64- The skill detects distributional discrepancies but does not identify root causes (instrumental drift, contamination, batch effects, or biological heterogeneity); manual inspection of pre- vs. post-normalization diagnostic plots is required to interpret findings.6566## Evidence6768- [other] Partition dataset into QC and biological subset; compute statistics per feature per subset; calculate discrepancy metrics; apply threshold; generate report: "Partition the dataset into QC sample subset and biological sample subset. 3. Compute distributional statistics (mean, variance, or robust quantiles) for each metabolic feature within each subset. 4."69- [intro] Joint normalization with QC check is recommended; discrepancies between QC and biological samples indicate normalization issues: "We further recommend using both QC as well as biological samples for normalization, and to have metanorm check for discrepancies between QC and biological samples"70- [readme] QCcheck parameter in Metanorm enables discrepancy detection during normalization workflow: "QCcheck = TRUE, # check whether QCs are representative"71- [readme] Diagnostic plots are essential for interpreting discrepancies and assessing normalization performance: "Individual compound pre- vs. post-normalization intensity vs. order plots can be retrieved from the *plotdir* directory. These allow finegrained assessment of normalization performance. It is highly"
HolobiomicsLab