Bioconductor Summarized Experiment Construction

bioconductor-summarized-experiment-construction

Summary

Convert a validated tab-delimited metabolomics data frame into a Bioconductor SummarizedExperiment object with automatically computed assays (primary compound areas, internal standard areas, and compound/IS ratios) and structured metadata. This skill bridges raw data import and downstream quality control analysis in mzQuality workflows.

When to use

After successfully reading and validating a tab-delimited metabolomics file (containing mandatory columns: aliquot, compound, area, type, injection_time, batch) using readData, and before applying batch correction, outlier detection, or other QC filters. Use this skill when you have a data frame with metabolite measurements indexed by sample and compound identifiers, and need to construct a structured object that preserves both assay data and sample/feature metadata.

When NOT to use

• Data is already in SummarizedExperiment format (use directly or convert via coercion instead)
• Input file has missing or incorrectly formatted mandatory columns—run readData validation first and correct before calling buildExperiment
• No internal standard (secondary assay) is defined or available; ratio assay computation will fail silently or produce NA values

Inputs

• data frame from readData() with validated columns: aliquot, compound, area, type, injection_time, batch
• column name specifying compound/feature identifier (string)
• column name specifying aliquot/sample identifier (string)
• column name for primary assay values, typically peak area (string)
• column name for secondary assay values, typically internal standard area (string)

Outputs

• SummarizedExperiment object with three assays: primary compound areas, internal standard areas, and computed compound/IS ratios
• rowData slot containing compound metadata (indexed by feature name)
• colData slot containing sample metadata including batch, injection_time, and sample type
• assay slot with three named matrices: primaryAssay, secondaryAssay, and ratio

How to apply

Call buildExperiment() on the validated data frame returned by readData(), specifying the compoundColumn (feature identifier, e.g., 'compound'), aliquotColumn (sample identifier, e.g., 'aliquot'), primaryAssay (e.g., 'area' for compound peak area), and secondaryAssay (e.g., 'area' for internal standard peak area when type='IS'). The function automatically deduces rowData from unique compounds and colData from unique samples, infers batch and injection_time metadata, and computes the compound/internal standard ratio assay by dividing primary by secondary assay values for each sample. Verify the resulting SummarizedExperiment contains three assays (primaryAssay, secondaryAssay, ratio), rowData indexed by compound with metadata columns, and colData indexed by aliquot with sample type, batch, and injection metadata.

Related tools

• mzQuality (R package providing buildExperiment() function to construct SummarizedExperiment from validated metabolomics data frames) — https://github.com/hankemeierlab/mzQuality
• SummarizedExperiment (Bioconductor S4 class used internally by mzQuality to store assay data and associated metadata in structured rowData and colData slots) — https://bioconductor.org/packages/release/bioc/html/SummarizedExperiment.html
• readData (mzQuality function that reads tab-delimited files and validates mandatory columns before passing to buildExperiment) — https://github.com/hankemeierlab/mzQuality
• mzQualityDashboard (Interactive Shiny application wrapping mzQuality's buildExperiment for users without R programming experience) — https://github.com/hankemeierlab/mzQualityDashboard

Examples

path <- system.file("extdata", "example.tsv", package = "mzQuality"); exp <- buildExperiment(readData(path))

Evaluation signals

• Resulting object is a valid SummarizedExperiment with class 'SummarizedExperiment' (check via class() in R)
• Three named assays are present: verify via names(assays(exp)) returns at least [primaryAssay, secondaryAssay, ratio]
• Ratio assay values are correctly computed as primary/secondary for each sample; spot-check a few cells: assays(exp)$ratio[i,j] ≈ assays(exp)$primaryAssay[i,j] / assays(exp)$secondaryAssay[i,j]
• rowData contains one row per unique compound with no duplicate feature names; nrow(rowData(exp)) equals number of unique compounds in input
• colData contains one row per unique sample with batch and injection_time metadata; nrow(colData(exp)) equals number of unique aliquots in input
• No NA values appear in ratio assay where both primary and secondary assay values are non-zero and non-missing

Limitations

• buildExperiment requires all mandatory columns (aliquot, compound, area, type, injection_time, batch) to be present and correctly formatted; missing or misspelled columns will cause function failure—use readData() for validation first
• Ratio assay computation assumes secondary assay (internal standard) is always present for every sample; samples missing internal standard measurements will produce NA in ratio assay
• Function does not perform batch correction or outlier detection; these are separate downstream steps (doAnalysis) applied after object construction
• Large datasets (105+ compounds × 500+ samples) may consume significant memory as assays are stored as dense matrices; sparse matrix support is not documented

Evidence

• [other] buildExperiment deduces rowData and colData slots from compoundColumn and aliquotColumn, uses primaryAssay and secondaryAssay as compound and Internal Standard areas respectively, and automatically calculates the compound/Internal Standard ratio for each sample, storing it in the ratio assay.: "buildExperiment deduces rowData and colData slots from compoundColumn and aliquotColumn, uses primaryAssay and secondaryAssay as compound and Internal Standard areas respectively, and automatically"
• [intro] The function buildExperiment allows you to create a SummarizedExperiment object from a data frame by specifying the following columns: "The function buildExperiment allows you to create a SummarizedExperiment object from a data frame by specifying the following columns"
• [other] To read your data, you can use the readData function. This function will read in your data and check for any missing or incorrect columns.: "To read your data, you can use the readData function. This function will read in your data and check for any missing or incorrect columns."
• [readme] Once your files are ready, you can use the readData function to read in your data. It will check if all mandatory columns are present and if the data is in the correct format. Finally, the function buildExperiment will convert the data into a SummarizedExperiment object.: "Finally, the function buildExperiment will convert the data into a SummarizedExperiment object. This is the object that mzQuality uses to perform all calculations and analyses"
• [readme] path <- system.file("extdata", "example.tsv", package = "mzQuality"); exp <- buildExperiment(readData(path)): "exp <- buildExperiment(readData(path))"