batch-corrected-data-visualization
Summary
Generate publication-ready plots and interactive visualizations of batch-corrected metabolomics data to inspect data quality, compound distributions, and sample clustering. This skill transforms post-analysis SummarizedExperiment objects into diagnostic plots and dimensionality reduction views that reveal batch effects, outlier patterns, and compound reliability.
When to use
After doAnalysis() has been completed and batch correction applied (ratio_corrected assay populated), use this skill when you need to inspect the effect of batch correction on QC sample clustering, verify that study samples group appropriately by type or aliquot, or identify remaining outliers or unreliable compounds before generating final reports. Apply this skill before subsetting compounds/samples or calling createReports() to validate analysis outcomes.
When NOT to use
- Input SummarizedExperiment has not been processed by doAnalysis() (assay 'ratio_corrected' does not exist; use doAnalysis first).
- Goal is to export final reports and tab-delimited data tables (use createReports instead).
- Data is in raw, unbatched format with no QC samples available for batch correction assessment.
Inputs
- SummarizedExperiment object with doAnalysis results (rowData, colData, and assay 'ratio_corrected' populated)
- Batch and sample type annotations in colData
- Compound quality flags (use=TRUE/FALSE) in rowData
Outputs
- PCA plot showing aliquot/sample distribution per type and batch
- Compound scatterplots (ratio_corrected assay values across samples)
- Violin plots stratified by sample type
- Boxplots of all compound values across aliquots
- Interactive Shiny dashboard (mzQualityDashboard) with linked plots and data tables
How to apply
Load the post-analysis SummarizedExperiment object (output of doAnalysis) into R. Select the appropriate assay slot—typically 'ratio_corrected' for batch-corrected compound/internal standard ratios. Call plotting functions such as pcaPlot() to visualize aliquot distribution per type and batch in PCA space, compoundPlot() to inspect individual compound intensities across samples, violinPlot() to compare distributions by sample type, and aliquotPlot() to create boxplots of all values across aliquots. These functions automatically extract colData and rowData annotations (sample type, batch, use flags) to color and stratify the plots. Inspect the plots to confirm that QC samples cluster tightly, study samples separate by expected phenotype/batch, and compounds marked use=TRUE show consistent signal and low variance relative to use=FALSE compounds. This visual inspection informs manual override of the automatic use flags if needed before subsetting.
Related tools
- mzQuality (Provides SummarizedExperiment object structure, batch correction (ratio_corrected assay), and plotting functions (pcaPlot, compoundPlot, violinPlot, aliquotPlot)) — https://github.com/hankemeierlab/mzQuality
- mzQualityDashboard (Interactive Shiny application frontend for visualizing and inspecting batch-corrected metabolomics data without programming) — https://github.com/hankemeierlab/mzQualityDashboard
- SummarizedExperiment (Bioconductor container class storing assays (ratio_corrected), rowData (compound annotations), and colData (sample metadata))
- R (Programming environment for loading data, calling plotting functions, and iterating on visualization parameters)
Examples
exp <- doAnalysis(exp = exp); pcaPlot(exp, assay = "ratio_corrected"); compoundPlot(exp, assay = "ratio_corrected"); violinPlot(exp)
Evaluation signals
- PCA plot shows QC samples (Pooled or Pooled Study QC) clustering tightly in PCA space, indicating successful batch correction.
- Violin plots and boxplots for compounds marked use=TRUE show lower inter-quartile range and smaller outlier spread compared to use=FALSE compounds.
- Study samples separate visibly by expected type (e.g., disease vs. control) or batch in PCA; no large unexplained clustering by batch after correction.
- Compounds with high RSDQC values or low presence in QC samples are visually confirmed as noisy (high variance, low signal) in compoundPlot views.
- Sample outliers identified by doAnalysis (Rosner test, use=FALSE in colData) are visually confirmed as distant in PCA or extreme in aliquot boxplots.
Limitations
- Plots reflect only the subset of compounds and samples currently in the SummarizedExperiment; subsetting must occur before plotting to visualize filtered data.
- PCA plots lose interpretability if the number of compounds with use=TRUE is very small (<5); consider retaining more marginal compounds temporarily for diagnostic plotting.
- Interactive mzQualityDashboard requires R/Shiny runtime; command-line plotting functions produce static images suitable for manuscripts but lack interactivity.
- Batch correction is performed only if SQC (pooled study quality control) samples are present; visualization of ratio_corrected assay without SQC will show uncorrected ratios.
Evidence
- [readme] PCA visualization across samples showing batch-corrected aliquot distribution: "Principal Component Analysis plot showing the aliquot distribution per type and batch for batch-corrected ratios"
- [readme] Multiple plotting functions available post-doAnalysis for batch-corrected inspection: "Boxplot of all values in aliquots/samples; Scatterplot of the compound / IS ratio for the first compound; Violinplot showing the distribution for a given sample type"
- [readme] doAnalysis produces batch-corrected ratios stored in assay slot: "Perform batch correction using the pooled study quality control samples (SQC)"
- [readme] Compound and sample quality flags guide interpretation of batch-corrected plots: "mzQuality adds a column called
use in both the rowData and colData slots of the SummarizedExperiment. These contain either a TRUE or FALSE value, indicating if the compound or sample is"
- [readme] SummarizedExperiment is the core object structure holding all assays and annotations: "The result is a SummarizedExperiment, which is the core object that mzQuality uses"
1---2name: batch-corrected-data-visualization3description: Use when after doAnalysis() has been completed and batch correction applied (ratio_corrected assay populated), use this skill when you need to inspect the effect of batch correction on QC sample clustering, verify that study samples group appropriately by type or aliquot, or identify remaining.4license: CC-BY-4.05---67# batch-corrected-data-visualization89## Summary1011Generate publication-ready plots and interactive visualizations of batch-corrected metabolomics data to inspect data quality, compound distributions, and sample clustering. This skill transforms post-analysis SummarizedExperiment objects into diagnostic plots and dimensionality reduction views that reveal batch effects, outlier patterns, and compound reliability.1213## When to use1415After doAnalysis() has been completed and batch correction applied (ratio_corrected assay populated), use this skill when you need to inspect the effect of batch correction on QC sample clustering, verify that study samples group appropriately by type or aliquot, or identify remaining outliers or unreliable compounds before generating final reports. Apply this skill before subsetting compounds/samples or calling createReports() to validate analysis outcomes.1617## When NOT to use1819- Input SummarizedExperiment has not been processed by doAnalysis() (assay 'ratio_corrected' does not exist; use doAnalysis first).20- Goal is to export final reports and tab-delimited data tables (use createReports instead).21- Data is in raw, unbatched format with no QC samples available for batch correction assessment.2223## Inputs2425- SummarizedExperiment object with doAnalysis results (rowData, colData, and assay 'ratio_corrected' populated)26- Batch and sample type annotations in colData27- Compound quality flags (use=TRUE/FALSE) in rowData2829## Outputs3031- PCA plot showing aliquot/sample distribution per type and batch32- Compound scatterplots (ratio_corrected assay values across samples)33- Violin plots stratified by sample type34- Boxplots of all compound values across aliquots35- Interactive Shiny dashboard (mzQualityDashboard) with linked plots and data tables3637## How to apply3839Load the post-analysis SummarizedExperiment object (output of doAnalysis) into R. Select the appropriate assay slot—typically 'ratio_corrected' for batch-corrected compound/internal standard ratios. Call plotting functions such as pcaPlot() to visualize aliquot distribution per type and batch in PCA space, compoundPlot() to inspect individual compound intensities across samples, violinPlot() to compare distributions by sample type, and aliquotPlot() to create boxplots of all values across aliquots. These functions automatically extract colData and rowData annotations (sample type, batch, use flags) to color and stratify the plots. Inspect the plots to confirm that QC samples cluster tightly, study samples separate by expected phenotype/batch, and compounds marked use=TRUE show consistent signal and low variance relative to use=FALSE compounds. This visual inspection informs manual override of the automatic use flags if needed before subsetting.4041## Related tools4243- **mzQuality** (Provides SummarizedExperiment object structure, batch correction (ratio_corrected assay), and plotting functions (pcaPlot, compoundPlot, violinPlot, aliquotPlot)) — https://github.com/hankemeierlab/mzQuality44- **mzQualityDashboard** (Interactive Shiny application frontend for visualizing and inspecting batch-corrected metabolomics data without programming) — https://github.com/hankemeierlab/mzQualityDashboard45- **SummarizedExperiment** (Bioconductor container class storing assays (ratio_corrected), rowData (compound annotations), and colData (sample metadata))46- **R** (Programming environment for loading data, calling plotting functions, and iterating on visualization parameters)4748## Examples4950```51exp <- doAnalysis(exp = exp); pcaPlot(exp, assay = "ratio_corrected"); compoundPlot(exp, assay = "ratio_corrected"); violinPlot(exp)52```5354## Evaluation signals5556- PCA plot shows QC samples (Pooled or Pooled Study QC) clustering tightly in PCA space, indicating successful batch correction.57- Violin plots and boxplots for compounds marked use=TRUE show lower inter-quartile range and smaller outlier spread compared to use=FALSE compounds.58- Study samples separate visibly by expected type (e.g., disease vs. control) or batch in PCA; no large unexplained clustering by batch after correction.59- Compounds with high RSDQC values or low presence in QC samples are visually confirmed as noisy (high variance, low signal) in compoundPlot views.60- Sample outliers identified by doAnalysis (Rosner test, use=FALSE in colData) are visually confirmed as distant in PCA or extreme in aliquot boxplots.6162## Limitations6364- Plots reflect only the subset of compounds and samples currently in the SummarizedExperiment; subsetting must occur before plotting to visualize filtered data.65- PCA plots lose interpretability if the number of compounds with use=TRUE is very small (<5); consider retaining more marginal compounds temporarily for diagnostic plotting.66- Interactive mzQualityDashboard requires R/Shiny runtime; command-line plotting functions produce static images suitable for manuscripts but lack interactivity.67- Batch correction is performed only if SQC (pooled study quality control) samples are present; visualization of ratio_corrected assay without SQC will show uncorrected ratios.6869## Evidence7071- [readme] PCA visualization across samples showing batch-corrected aliquot distribution: "Principal Component Analysis plot showing the aliquot distribution per type and batch for batch-corrected ratios"72- [readme] Multiple plotting functions available post-doAnalysis for batch-corrected inspection: "Boxplot of all values in aliquots/samples; Scatterplot of the compound / IS ratio for the first compound; Violinplot showing the distribution for a given sample type"73- [readme] doAnalysis produces batch-corrected ratios stored in assay slot: "Perform batch correction using the pooled study quality control samples (SQC)"74- [readme] Compound and sample quality flags guide interpretation of batch-corrected plots: "mzQuality adds a column called `use` in both the `rowData` and `colData` slots of the SummarizedExperiment. These contain either a `TRUE` or `FALSE` value, indicating if the compound or sample is"75- [readme] SummarizedExperiment is the core object structure holding all assays and annotations: "The result is a SummarizedExperiment, which is the core object that mzQuality uses"
HolobiomicsLab 