R Bioconductor SummarizedExperiment Manipulation
Summary
Create, populate, and modify Bioconductor SummarizedExperiment objects to store and organize multi-dimensional omics data (assays, row metadata, column metadata) for downstream quality control and statistical analysis. This skill is foundational for working with metabolomics and other -omics datasets in R pipelines.
When to use
When converting raw metabolomics data (tab-delimited text files, Sciex OS exports) into a structured object for batch processing, or when you need to organize compound-level measurements (assays), sample metadata (colData), and feature annotations (rowData) in a single container that downstream analysis functions like mzQuality's doAnalysis or createReports expect.
When NOT to use
- Input is already a SummarizedExperiment object and does not require re-building or column validation.
- Data is in a different Bioconductor container (e.g., MSnSet, ExpressionSet) that is not compatible with mzQuality's expected SummarizedExperiment schema.
- Raw instrument files (e.g., .raw, .d, .mzML) need peak-picking and feature detection first; buildExperiment expects pre-aligned, quantified data.
Inputs
- Tab-delimited text file with mandatory columns (compound name, sample ID, assay values, sample type, internal standard assignment)
- Sciex OS text export
- Data frame with compound, sample, and assay columns
- Pre-built SummarizedExperiment object
Outputs
- SummarizedExperiment object with assays (e.g., area, intensity, ratio, ratio_corrected)
- SummarizedExperiment object with updated rowData (compound-level metrics: RSDQC, background %, presence, use flag)
- SummarizedExperiment object with updated colData (sample-level metrics: outlier flags, batch, use flag)
- Subset SummarizedExperiment containing only reliable compounds and samples
How to apply
First, read your input data (tab-delimited format or Sciex OS text export) using readData, which validates mandatory columns (compound identifiers, sample identifiers, assay values such as area or intensity, and sample-type annotations). Next, call buildExperiment to convert the validated data frame into a SummarizedExperiment object, which organizes compounds as rows, samples as columns, and measurements (area, intensity, ratio) as assays. Populate rowData with compound-level metadata (e.g., internal standard assignment, chemical properties) and colData with sample-level metadata (e.g., sample type, batch, QC status). After analysis steps (e.g., doAnalysis for batch correction and quality metrics), the object's rowData and colData slots are updated with calculated columns (e.g., 'use' flags for reliability, RSDQC values, background percentages). Use subsetting (e.g., exp[rowData(exp)$use, exp$use]) to select reliable compounds and samples before visualization or export.
Related tools
- mzQuality (Package that requires SummarizedExperiment objects as input for outlier detection, batch correction, and quality metric calculation; doAnalysis populates assays and metadata slots.) — https://github.com/hankemeierlab/mzQuality
- SummarizedExperiment (Bioconductor core class used internally by mzQuality to store and access compound measurements, sample metadata, and assay data.)
- mzQualityDashboard (Shiny application that operates on SummarizedExperiment objects created and manipulated via buildExperiment and doAnalysis.) — https://github.com/hankemeierlab/mzQualityDashboard
Examples
path <- system.file("extdata", "example.tsv", package = "mzQuality"); exp <- buildExperiment(readData(path)); exp <- doAnalysis(exp = exp); exp_filtered <- exp[rowData(exp)$use, exp$use]
Evaluation signals
- SummarizedExperiment object dimensions match expected data: number of rows = number of compounds, number of columns = number of samples.
- assays() slot contains expected matrices with correct names (e.g., 'area', 'ratio', 'ratio_corrected'); all assays have identical dimensions.
- rowData() slot contains a DataFrame with one row per compound and columns for compound identifiers, internal standard assignment, and (after doAnalysis) calculated metrics (RSDQC, background %, presence, use flag).
- colData() slot contains a DataFrame with one row per sample and columns for sample metadata (sample ID, sample type, batch) and (after doAnalysis) outlier detection results and use flags.
- Subsetting operation exp[rowData(exp)$use, exp$use] produces a valid SummarizedExperiment with reduced dimensions and no NA values in the 'use' columns.
Limitations
- buildExperiment requires specific mandatory columns in the input data frame; missing or incorrectly named columns will cause readData validation to fail.
- In the current version of mzQuality, only one sample type (e.g., calibration line or quality control) can be used for calculating absolute concentrations; multi-sample-type concentration calculations are not supported.
- SummarizedExperiment subsetting by the 'use' flag is manual; there is no automatic filtering function built into the object class itself, requiring users to remember the correct subsetting syntax.
Evidence
- [intro] buildExperiment allows creation from a data frame with specified columns for compounds, samples, and assays: "The function
buildExperiment allows you to create a SummarizedExperiment object from a data frame by specifying the following columns"
- [intro] mzQuality uses SummarizedExperiment as its core internal data structure: "Internally, mzQuality uses Bioconductors' SummarizedExperiment object to store the data."
- [readme] readData validates input format and mandatory columns before buildExperiment: "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."
- [readme] doAnalysis updates assay, rowData, and colData slots with calculated metrics: "All calculations will be added to the
assay, rowData and colData slots of the experiment, or overwrite the values if they are already present."
- [readme] Subsetting using 'use' flag for reliable compounds and samples: "To retrieve the compounds and samples recommended by mzQuality, you can use the following code to subset the experiment: exp <- exp[rowData(exp)$use, exp$use]"
- [intro] Input data formats accepted: tab-delimited and Sciex OS text exports: "it features import of data from a variety of formats, including a generalized tab-delimited format and Sciex OS text exports."
- [other] Only one sample type can be used for concentration calculations in current version: "Note that in the current version of mzQuality, only one sample type can be used for calculating concentrations."
1---2name: r-bioconductor-summarizedexperiment-manipulation3description: Use when when converting raw metabolomics data (tab-delimited text files, Sciex OS exports) into a structured object for batch processing, or when you need to organize compound-level measurements (assays), sample metadata (colData), and feature annotations (rowData) in a single container that.4license: CC-BY-4.05---67# R Bioconductor SummarizedExperiment Manipulation89## Summary1011Create, populate, and modify Bioconductor SummarizedExperiment objects to store and organize multi-dimensional omics data (assays, row metadata, column metadata) for downstream quality control and statistical analysis. This skill is foundational for working with metabolomics and other -omics datasets in R pipelines.1213## When to use1415When converting raw metabolomics data (tab-delimited text files, Sciex OS exports) into a structured object for batch processing, or when you need to organize compound-level measurements (assays), sample metadata (colData), and feature annotations (rowData) in a single container that downstream analysis functions like mzQuality's doAnalysis or createReports expect.1617## When NOT to use1819- Input is already a SummarizedExperiment object and does not require re-building or column validation.20- Data is in a different Bioconductor container (e.g., MSnSet, ExpressionSet) that is not compatible with mzQuality's expected SummarizedExperiment schema.21- Raw instrument files (e.g., .raw, .d, .mzML) need peak-picking and feature detection first; buildExperiment expects pre-aligned, quantified data.2223## Inputs2425- Tab-delimited text file with mandatory columns (compound name, sample ID, assay values, sample type, internal standard assignment)26- Sciex OS text export27- Data frame with compound, sample, and assay columns28- Pre-built SummarizedExperiment object2930## Outputs3132- SummarizedExperiment object with assays (e.g., area, intensity, ratio, ratio_corrected)33- SummarizedExperiment object with updated rowData (compound-level metrics: RSDQC, background %, presence, use flag)34- SummarizedExperiment object with updated colData (sample-level metrics: outlier flags, batch, use flag)35- Subset SummarizedExperiment containing only reliable compounds and samples3637## How to apply3839First, read your input data (tab-delimited format or Sciex OS text export) using readData, which validates mandatory columns (compound identifiers, sample identifiers, assay values such as area or intensity, and sample-type annotations). Next, call buildExperiment to convert the validated data frame into a SummarizedExperiment object, which organizes compounds as rows, samples as columns, and measurements (area, intensity, ratio) as assays. Populate rowData with compound-level metadata (e.g., internal standard assignment, chemical properties) and colData with sample-level metadata (e.g., sample type, batch, QC status). After analysis steps (e.g., doAnalysis for batch correction and quality metrics), the object's rowData and colData slots are updated with calculated columns (e.g., 'use' flags for reliability, RSDQC values, background percentages). Use subsetting (e.g., exp[rowData(exp)$use, exp$use]) to select reliable compounds and samples before visualization or export.4041## Related tools4243- **mzQuality** (Package that requires SummarizedExperiment objects as input for outlier detection, batch correction, and quality metric calculation; doAnalysis populates assays and metadata slots.) — https://github.com/hankemeierlab/mzQuality44- **SummarizedExperiment** (Bioconductor core class used internally by mzQuality to store and access compound measurements, sample metadata, and assay data.)45- **mzQualityDashboard** (Shiny application that operates on SummarizedExperiment objects created and manipulated via buildExperiment and doAnalysis.) — https://github.com/hankemeierlab/mzQualityDashboard4647## Examples4849```50path <- system.file("extdata", "example.tsv", package = "mzQuality"); exp <- buildExperiment(readData(path)); exp <- doAnalysis(exp = exp); exp_filtered <- exp[rowData(exp)$use, exp$use]51```5253## Evaluation signals5455- SummarizedExperiment object dimensions match expected data: number of rows = number of compounds, number of columns = number of samples.56- assays() slot contains expected matrices with correct names (e.g., 'area', 'ratio', 'ratio_corrected'); all assays have identical dimensions.57- rowData() slot contains a DataFrame with one row per compound and columns for compound identifiers, internal standard assignment, and (after doAnalysis) calculated metrics (RSDQC, background %, presence, use flag).58- colData() slot contains a DataFrame with one row per sample and columns for sample metadata (sample ID, sample type, batch) and (after doAnalysis) outlier detection results and use flags.59- Subsetting operation exp[rowData(exp)$use, exp$use] produces a valid SummarizedExperiment with reduced dimensions and no NA values in the 'use' columns.6061## Limitations6263- buildExperiment requires specific mandatory columns in the input data frame; missing or incorrectly named columns will cause readData validation to fail.64- In the current version of mzQuality, only one sample type (e.g., calibration line or quality control) can be used for calculating absolute concentrations; multi-sample-type concentration calculations are not supported.65- SummarizedExperiment subsetting by the 'use' flag is manual; there is no automatic filtering function built into the object class itself, requiring users to remember the correct subsetting syntax.6667## Evidence6869- [intro] buildExperiment allows creation from a data frame with specified columns for compounds, samples, and assays: "The function `buildExperiment` allows you to create a *SummarizedExperiment* object from a data frame by specifying the following columns"70- [intro] mzQuality uses SummarizedExperiment as its core internal data structure: "Internally, mzQuality uses Bioconductors' *SummarizedExperiment* object to store the data."71- [readme] readData validates input format and mandatory columns before buildExperiment: "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."72- [readme] doAnalysis updates assay, rowData, and colData slots with calculated metrics: "All calculations will be added to the `assay`, `rowData` and `colData` slots of the experiment, or overwrite the values if they are already present."73- [readme] Subsetting using 'use' flag for reliable compounds and samples: "To retrieve the compounds and samples recommended by mzQuality, you can use the following code to subset the experiment: exp <- exp[rowData(exp)$use, exp$use]"74- [intro] Input data formats accepted: tab-delimited and Sciex OS text exports: "it features import of data from a variety of formats, including a generalized tab-delimited format and Sciex OS text exports."75- [other] Only one sample type can be used for concentration calculations in current version: "Note that in the current version of mzQuality, only one sample type can be used for calculating concentrations."
HolobiomicsLab