Compound Metric Tabulation

compound-metric-tabulation

Summary

Export quality control metrics and assay values for all compounds into tab-delimited and Excel files after mzQuality analysis. This skill enables programmatic access to batch-corrected ratios, RSDQC, background signal percentages, matrix effects, and presence/concentration data for downstream reporting and integration.

When to use

After completing doAnalysis on a SummarizedExperiment object with mzQuality, when you need to share compound-level metrics with non-R users, integrate results into downstream reporting systems, or perform meta-analyses across multiple metabolomics experiments. Specifically triggered when makeSummaryReport or makeCompoundReport flags are set to TRUE in createReports.

When NOT to use

• If the experiment object has not yet been processed with doAnalysis — metrics such as RSDQC, batch correction, and background signal will not be available.
• If you only need interactive visualization of results — use the mzQualityDashboard Shiny application instead for exploratory browsing without file export.
• If the dataset contains no QC samples — mzQuality cannot calculate batch-corrected ratios or RSDQC, making compound reports incomplete.

Inputs

• SummarizedExperiment object (result of doAnalysis with outlier detection, batch correction, and quality metrics calculated)
• Boolean flags: makeSummaryReport, makeCompoundReport
• Output directory path

Outputs

• Project folder containing Reports subdirectory
• Tab-delimited text files (rowData, colData, assays: ratio, ratio_corrected, background_signal_pct, matrix_effect, median_area, presence, concentration, R2)
• Excel workbook (.xlsx) with all data in separate sheets
• HTML summary and compound reports (when enabled)

How to apply

Call createReports on the analyzed experiment object (result of doAnalysis) with makeSummaryReport=TRUE and makeCompoundReport=TRUE to generate tab-delimited text files and an Excel workbook. The function exports rowData (compound annotations and metrics) and all assays (ratio, ratio_corrected, background signal percentage, matrix effect, median area, presence, concentration if calibration lines were supplied, and R² values) into separate sheets. The exported files are organized into a Project folder with Reports subdirectory. Verify that tab-delimited files are readable in spreadsheet applications and that all calculated metrics (RSDQC, background %, matrix effect, presence) are present for each compound. Subset the experiment to include only compounds and samples marked use=TRUE in rowData and colData before export to ensure only reliable results are reported.

Related tools

• mzQuality (Core R package that calculates metrics (RSDQC, batch correction, background signal, matrix effect) and provides createReports function for tabulation export) — https://github.com/hankemeierlab/mzQuality
• SummarizedExperiment (Bioconductor data structure that stores compound metrics in rowData, sample metadata in colData, and assay matrices (ratio, ratio_corrected, etc.)) — https://bioconductor.org/packages/release/bioc/html/SummarizedExperiment.html
• R (Statistical computing environment in which mzQuality and createReports are executed)
• mzQualityDashboard (Shiny-based GUI alternative for interactive viewing and export without requiring R scripting) — https://github.com/hankemeierlab/mzQualityDashboard

Examples

exp <- doAnalysis(exp); createReports(exp, path='output_dir', makeSummaryReport=TRUE, makeCompoundReport=TRUE)

Evaluation signals

• Project folder created in specified output directory with Reports subdirectory present
• Tab-delimited files are readable and contain expected columns: compound identifiers, RSDQC values, background signal percentages, matrix effect, median area, presence counts, and (if calibration supplied) concentrations and R² values
• Excel file contains separate sheets for rowData, colData, and each assay (ratio, ratio_corrected, background_signal_pct, matrix_effect, median_area, presence, concentration, R2) with matching row/column counts to the original SummarizedExperiment
• Number of rows in exported compound files equals number of TRUE entries in rowData$use; number of columns in exported sample files equals number of TRUE entries in colData$use
• Batch-corrected ratio values (ratio_corrected assay) show lower variance than uncorrected ratios in QC samples, confirming batch correction was applied before export

Limitations

• Tab-delimited format may have issues with special characters or very large datasets; Excel format has row limit (~1 million rows) for some versions.
• Concentrations and R² values are only exported if calibration line samples with known concentrations were supplied during doAnalysis; otherwise those columns will be absent.
• createReports exports the entire filtered experiment; no in-situ filtering of compounds by RSDQC threshold or presence threshold is possible — pre-filter via rowData$use subsetting before calling createReports.
• The exported tab-delimited files contain no markdown or formatting; all visualization context (plots, HTML annotations) resides in the parallel Plots subdirectory and HTML reports, not in the tabular exports.

Evidence

• [other] Generates a Project folder organized into Plots and Reports subdirectories containing analysis results, including summary reports, compound reports, and tab-delimited text files for programmatic access.: "createReports generates a Project folder organized into Plots and Reports subdirectories containing analysis results, including summary reports, compound reports, and tab-delimited text files for"
• [readme] createReports creates a folder containing HTML files with plots, tab-delimited files containing the colData, rowData, and the various assays, and an Excel file that contains all the data in a single file.: "createReports will create a folder containing HTML files with plots, tab-delimited files containing the colData, rowData, and the various assays, and an Excel file that contains all the data in"
• [other] Call createReports with the experiment object, setting makeSummaryReport=TRUE and makeCompoundReport=TRUE to enable both report types.: "Call createReports with the experiment object, setting makeSummaryReport=TRUE and makeCompoundReport=TRUE to enable both report types."
• [readme] The doAnalysis function will perform the following steps: 1. Calculate the ratio between the compounds and assigned internal standards, 2. Perform batch correction using the pooled study quality control samples (SQC), 3. Calculate the percentage of background signal compared to the study samples, 4. Calculate the matrix effect, 5. Calculate the ratio of the QC sample, 6. Calculate the presence of the compounds in the samples, 7. Calculate the median area of the compounds in the samples, 8. Suggest Internal Standards based on the calculated values.: "The doAnalysis function will perform the following steps: 1. Calculate the ratio between the compounds and assigned internal standards, 2. Perform batch correction using the pooled study quality"
• [readme] 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 reliable for reporting based on the set thresholds.: "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"