SummarizedExperiment Assay Manipulation
Summary
Create, transform, and extract assays within SummarizedExperiment objects to support multi-stage metabolomics data processing pipelines. This skill enables chaining of normalization, imputation, and batch-correction workflows while preserving sample and feature metadata.
When to use
When working with multi-batch metabolomics studies where you need to create intermediate normalized assays (e.g., logRaw, rawImpute, loessShort_concatenate) at each processing stage, and downstream analysis tools expect data in SummarizedExperiment format with assay names tracked as formal object attributes rather than loose matrices.
When NOT to use
- Input is a simple matrix or data.frame without sample/feature metadata—use SummarizedExperiment construction first.
- Assay dimensions are inconsistent (metabolite or sample count differs across assays)—fix dimension mismatches before assignment.
- You need to store non-numeric metadata or per-assay parameters—use metadata() or altExp() slots instead of assay slots for those.
Inputs
- SummarizedExperiment object with one or more named assays (e.g., 'raw', 'logRaw')
- Numeric matrix of metabolite abundances (metabolites × samples)
- colData with batch and replicate metadata
- rowData with metabolite identifiers
Outputs
- SummarizedExperiment object with new named assay(s) appended (e.g., 'rawImpute', 'loessShort_concatenate')
- Extracted assay matrix for external tool input
- Updated colData and rowData preserved alongside new assays
How to apply
Load or construct a SummarizedExperiment object containing raw metabolite abundance data in a named assay (e.g., 'raw'). Apply transformations by computing new assay matrices—such as log2(raw + 1) for loess-compatible scaling, k-nearest neighbor imputation for missing values, or RUV-III batch correction—and attach each result to the same SummarizedExperiment using assay(object, 'newAssayName') <- result_matrix. Verify that row and column dimensions match the original object (metabolites × samples) and that metadata in colData (batch, replicate flags) and rowData remain aligned. Extract final assays using assay(object, 'assayName') for downstream tools.
Related tools
- SummarizedExperiment (Container class for storing metabolite abundance matrices with aligned sample and feature metadata across multiple normalization stages) — https://bioconductor.org/packages/SummarizedExperiment
- hRUV (Batch normalization pipeline that accepts SummarizedExperiment inputs and returns updated objects with new assays (rawImpute, loessShort_concatenate, etc.)) — https://github.com/SydneyBioX/hRUV
- dplyr (Data transformation and metadata manipulation for colData and rowData annotations)
Examples
assay(dat, "logRaw", withDimnames = FALSE) <- log2(assay(dat, "raw") + 1); dat_list <- hRUV::clean(dat_list, threshold = 0.5, method = "intersect", assay = "logRaw", newAssay = "rawImpute")
Evaluation signals
- Verify assay name is registered: names(assays(object)) includes the new assay string.
- Check matrix dimensions are consistent: nrow(assay(object, 'newAssay')) == nrow(object) and ncol(...) == ncol(object).
- Confirm colData and rowData match object dimensions: nrow(colData(object)) == ncol(object), nrow(rowData(object)) == nrow(object).
- Validate no NA introduction: sum(is.na(assay(object, 'newAssay'))) is acceptable given imputation method (e.g., 0 if kNN imputed).
- Trace metadata preservation: batch and replicate annotations in colData should be unchanged across assay operations.
Limitations
- SummarizedExperiment does not enforce assay name uniqueness; overwriting an existing assay name silently replaces prior data.
- Memory usage scales with matrix size and number of assays stored; large metabolomics studies (>10k metabolites × >1k samples) may require memory-aware assay subsetting.
- Row and column dimension mismatches will cause runtime errors during assay assignment; no automatic reconciliation is performed.
- Cross-assay operations (e.g., comparing values across 'raw' and 'logRaw') require manual extraction and alignment; the object itself provides no join semantics.
Evidence
- [intro] Log transformation via assay assignment: "assay(dat, "logRaw", withDimnames = FALSE) = log2(assay(dat, "raw") + 1)"
- [intro] Multi-assay workflow in hRUV pipeline: "dat_list = hRUV::clean(dat_list, threshold = 0.5, method = "intersect", assay = "logRaw", newAssay = "rawImpute")"
- [intro] SummarizedExperiment as standard container: "The data is already formatted in to a
SummarizedExperiment object"
- [methods] Assay extraction from normalized output: "Extract the resulting normalised loessShort_concatenate assay from the returned SummarizedExperiment object"
- [other] Multiple assay names in single object: "Extract and verify the rawImpute assay from the cleaned output, confirming metabolite count reduction and absence of missing values"
1---2name: summarizedexperiment-assay-manipulation3description: Use when when working with multi-batch metabolomics studies where you need to create intermediate normalized assays (e.4license: CC-BY-4.05---67# SummarizedExperiment Assay Manipulation89## Summary1011Create, transform, and extract assays within SummarizedExperiment objects to support multi-stage metabolomics data processing pipelines. This skill enables chaining of normalization, imputation, and batch-correction workflows while preserving sample and feature metadata.1213## When to use1415When working with multi-batch metabolomics studies where you need to create intermediate normalized assays (e.g., logRaw, rawImpute, loessShort_concatenate) at each processing stage, and downstream analysis tools expect data in SummarizedExperiment format with assay names tracked as formal object attributes rather than loose matrices.1617## When NOT to use1819- Input is a simple matrix or data.frame without sample/feature metadata—use SummarizedExperiment construction first.20- Assay dimensions are inconsistent (metabolite or sample count differs across assays)—fix dimension mismatches before assignment.21- You need to store non-numeric metadata or per-assay parameters—use metadata() or altExp() slots instead of assay slots for those.2223## Inputs2425- SummarizedExperiment object with one or more named assays (e.g., 'raw', 'logRaw')26- Numeric matrix of metabolite abundances (metabolites × samples)27- colData with batch and replicate metadata28- rowData with metabolite identifiers2930## Outputs3132- SummarizedExperiment object with new named assay(s) appended (e.g., 'rawImpute', 'loessShort_concatenate')33- Extracted assay matrix for external tool input34- Updated colData and rowData preserved alongside new assays3536## How to apply3738Load or construct a SummarizedExperiment object containing raw metabolite abundance data in a named assay (e.g., 'raw'). Apply transformations by computing new assay matrices—such as log2(raw + 1) for loess-compatible scaling, k-nearest neighbor imputation for missing values, or RUV-III batch correction—and attach each result to the same SummarizedExperiment using assay(object, 'newAssayName') <- result_matrix. Verify that row and column dimensions match the original object (metabolites × samples) and that metadata in colData (batch, replicate flags) and rowData remain aligned. Extract final assays using assay(object, 'assayName') for downstream tools.3940## Related tools4142- **SummarizedExperiment** (Container class for storing metabolite abundance matrices with aligned sample and feature metadata across multiple normalization stages) — https://bioconductor.org/packages/SummarizedExperiment43- **hRUV** (Batch normalization pipeline that accepts SummarizedExperiment inputs and returns updated objects with new assays (rawImpute, loessShort_concatenate, etc.)) — https://github.com/SydneyBioX/hRUV44- **dplyr** (Data transformation and metadata manipulation for colData and rowData annotations)4546## Examples4748```49assay(dat, "logRaw", withDimnames = FALSE) <- log2(assay(dat, "raw") + 1); dat_list <- hRUV::clean(dat_list, threshold = 0.5, method = "intersect", assay = "logRaw", newAssay = "rawImpute")50```5152## Evaluation signals5354- Verify assay name is registered: names(assays(object)) includes the new assay string.55- Check matrix dimensions are consistent: nrow(assay(object, 'newAssay')) == nrow(object) and ncol(...) == ncol(object).56- Confirm colData and rowData match object dimensions: nrow(colData(object)) == ncol(object), nrow(rowData(object)) == nrow(object).57- Validate no NA introduction: sum(is.na(assay(object, 'newAssay'))) is acceptable given imputation method (e.g., 0 if kNN imputed).58- Trace metadata preservation: batch and replicate annotations in colData should be unchanged across assay operations.5960## Limitations6162- SummarizedExperiment does not enforce assay name uniqueness; overwriting an existing assay name silently replaces prior data.63- Memory usage scales with matrix size and number of assays stored; large metabolomics studies (>10k metabolites × >1k samples) may require memory-aware assay subsetting.64- Row and column dimension mismatches will cause runtime errors during assay assignment; no automatic reconciliation is performed.65- Cross-assay operations (e.g., comparing values across 'raw' and 'logRaw') require manual extraction and alignment; the object itself provides no join semantics.6667## Evidence6869- [intro] Log transformation via assay assignment: "assay(dat, "logRaw", withDimnames = FALSE) = log2(assay(dat, "raw") + 1)"70- [intro] Multi-assay workflow in hRUV pipeline: "dat_list = hRUV::clean(dat_list, threshold = 0.5, method = "intersect", assay = "logRaw", newAssay = "rawImpute")"71- [intro] SummarizedExperiment as standard container: "The data is already formatted in to a `SummarizedExperiment` object"72- [methods] Assay extraction from normalized output: "Extract the resulting normalised loessShort_concatenate assay from the returned SummarizedExperiment object"73- [other] Multiple assay names in single object: "Extract and verify the rawImpute assay from the cleaned output, confirming metabolite count reduction and absence of missing values"
