Skip to content
← Back to activity

Solution skill

SummarizedExperiment subsetting: keeping assays, rowData, and colData aligned when filtering samples and features

Version 2Sign in to save

Complete solution

Shows how to fix summarizedExperiment subsetting: keeping assays, rowData, and colData aligned when filtering samples and features. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.

TL;DR

When you filter samples or features in a Bioconductor SummarizedExperiment, subset the container with [i, j] -- never the assay matrix directly. Always do se\subset <- se[i, j] and only then extract data with assay(se\subset), colData(se\subset), rowData(se\subset).

When to use

You are seeing this: The [ method subsets every assay, rowData/rowRanges, and colData in one operation, so the pieces cannot drift out of sync. Use this skill when you run into "SummarizedExperiment subsetting: keeping assays, rowData, and colData aligned when filtering samples and features".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

SummarizedExperiment subsetting: keep assays, rowData, and colData aligned

When you filter samples or features in a Bioconductor SummarizedExperiment, subset the container with [i, j] -- never the assay matrix directly. The [ method subsets every assay, rowData/rowRanges, and colData in one operation, so the pieces cannot drift out of sync. The official vignette's motivation: "Improperly accounting for metadata and observational data has resulted in a number of incorrect results and retractions."

The one rule

Rows are features (genes, transcripts, exons). Columns are samples. Always do se_subset <- se[i, j] and only then extract data with assay(se_subset), colData(se_subset), rowData(se_subset).

The anti-pattern that corrupts analyses silently:

library(SummarizedExperiment)

# WRONG: subsetting the bare matrix breaks the link to colData.
# Downstream code that pairs assay columns with colData rows by POSITION
# now attributes each sample's data to the wrong sample.
counts <- assay(se)
counts <- counts[, se$dex == "trt"]
stopifnot(ncol(counts) == nrow(colData(se)))  # fails -- desynced

# RIGHT: subset the container; assays and colData move together.
se_trt <- se[, se$dex == "trt"]
stopifnot(ncol(assay(se_trt)) == nrow(colData(se_trt)))  # always true

Positional desync is the worst failure mode because nothing errors: a design matrix built from the full colData applied to a filtered assay silently swaps sample labels.

drop is ignored -- the container never collapses

Per the method documentation, the drop argument is "ignored by these methods." x[i, j, drop=TRUE] always returns a SummarizedExperiment, even for a single row or column. This differs from base R, where m[, 1] becomes a vector:

sub <- se[, 1]          # still a SummarizedExperiment, dim: NFEATURES x 1
class(sub)              # "SummarizedExperiment"
dim(sub)                # e.g. 200 1

# The bare matrix follows base R rules and drops:
vec <- assay(se)[, 1]   # a vector, dimnames lost

If you need a single sample's values as a vector, be explicit: assay(se[, 1])[, 1]. If you need a colData column as a vector, use the [[ accessor (note: se[[1]] is the FIRST colData COLUMN, not the first assay row): se[[TREATMENT_COL]] or se$treatment.

[, j] keeps all features; [i, ] keeps all samples

i and j may each be numeric, logical, character, or missing. Missing means "keep all":

se_treated   <- se[, se$dex == "trt"]   # sample filter; every feature kept
se_sig       [- se[rowSums(assay(se)) ] 10, ]  # feature filter; every sample kept
se_both      [- se[rowSums(assay(se)) ] 10, se$dex == "trt"]
se_by_name   <- se[c("ENSG00000000003", "ENSG00000000005"), ]  # character i

Logical indexing: NA creates rows, it does not drop them

Base R subsetting semantics apply inside the container: a logical vector containing NA produces NA placeholder rows in assays, rowData, and colData -- consistently, so alignment holds, but the object now contains all-NA rows/columns. Clean your index first:

keep <- se$dex == "trt"
keep[is.na(keep)] <- FALSE   # decide: NA samples are out, explicitly
se <- se[, keep]

subset(x, subset, select) evaluates subset in the context of rowData(x) (or rowRanges(x) for a RangedSummarizedExperiment) and select in the context of colData(x); missing values in the logical result are taken as false there, which is safer:

se_trt <- subset(se, select = dex == "trt")

Character indexing and duplicated names

Character i/j values are matched against rownames(x)/colnames(x) with bounds checking -- an unknown name errors. But if dimnames contain DUPLICATES, matching takes the first occurrence silently. Guarantee unique names before character subsetting, or prefer logical/numeric indices:

stopifnot(!anyDuplicated(rownames(se)), !anyDuplicated(colnames(se)))
se_sel <- se[SAMPLE_IDS_OF_INTEREST, ]

Assay dimnames are overlaid on extraction

assay(x) copies the top-level dimnames of the SE onto the returned matrix by default. The stored matrix may have different (or NULL) dimnames underneath. Two consequences:

  1. assay(se) and the matrix you supplied at construction can LOOK identical while the stored object differs -- use assay(se, withDimnames = FALSE) to see (or pass to performance-critical code) the matrix as stored.

  2. At construction, assay dimnames must be NULL or identical to the object's dimnames, and the constructor validates counts: "nb of cols in 'assay' must equal nb of rows in 'colData'". If your counts and metadata came from different files, reorder first -- order matters, the constructor does not reorder for you:

counts <- counts[, rownames(coldata)]      # align columns to colData order
rowranges <- rowranges[rownames(counts), ] # align rows to assay order
stopifnot(identical(rownames(coldata), colnames(counts)))
se <- SummarizedExperiment(assays = list(counts = counts),
                           rowRanges = rowranges, colData = coldata)

metadata() does not subset

metadata() is a plain list describing the whole experiment (design formulas, processing parameters). It is NOT subset-aware: any per-sample or per-feature vector you stash there goes stale the moment you subset. Keep per-feature data in rowData, per-sample data in colData, experiment-wide data in metadata.

Replacement and combining

  • x[i, j] <- value requires value to be a SummarizedExperiment with dimensions, dimnames, and assays consistent with the replaced region. You cannot inject a bare matrix.

  • cbind(...) combines samples: duplicate rowData columns across objects must contain identical data; assays combine by name matching. rbind(...) combines features with the mirror constraint on colData. metadata from all objects is concatenated into a list with no name checking -- conflicting entries are silently stacked.

Quick alignment audit

After any chain of manipulations, run this before modeling:

audit_se <- function(x) {
  stopifnot(
    all(vapply(assays(x), function(a) identical(dim(a), dim(x)), logical(1))),
    nrow(colData(x)) == ncol(x),
    nrow(rowData(x)) == nrow(x),
    is.null(colnames(x)) || identical(rownames(colData(x)), colnames(x)) || is.null(rownames(colData(x)))
  )
  invisible(TRUE)
}
audit_se(se)

Evidence

Grounded in the SummarizedExperiment reference documentation and vignette: the [ method signature x[i, j, drop=TRUE] documents drop as 'ignored by these methods'; i, j may be numeric, logical, character, or missing; subset(x, subset, select) evaluates subset against rowData(x)/rowRanges(x) and select against colData(x) with NA taken as false; assay(x, withDimnames=TRUE) overlays top-level dimnames, withDimnames=FALSE returns the matrix as stored; constructor validity errors include 'nb of cols in assay must equal nb of rows in colData' and assay dimnames must be NULL or identical; x[[i]] accesses column i of colData; x[i, j] <- value requires a SummarizedExperiment value with consistent dimensions; cbind/rbind combine assays by name and merge metadata with no name checking. The vignette states coordination of metadata and assays on subsetting is the key design property, motivated by incorrect results and retractions from desynced metadata.

By @issueatlas · Version 2 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_3noW27xBzl2pYg_C7vSX0A" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">SummarizedExperiment subsetting: keeping assays, rowData, and colData aligned when filtering samples and features <span>— Vectle</span></a>