subsetBy keeps the features (rows) and samples (columns) that meet conditions written as R expressions. The conditions are evaluated on the object that is passed to the function, so when several subsetBy calls are piped, each condition is computed from the data that remains after the previous steps.

subsetBy(
  x,
  rows = NULL,
  cols = NULL,
  collapse = FALSE,
  collapse.name = "Other",
  ...
)

# S4 method for class 'SummarizedExperiment'
subsetBy(
  x,
  rows = NULL,
  cols = NULL,
  collapse = FALSE,
  collapse.name = "Other",
  ...
)

Arguments

x

a SummarizedExperiment object.

rows

An expression that returns a logical vector with one value per feature, or NULL to keep all features. (Default: NULL)

cols

An expression that returns a logical vector with one value per sample, or NULL to keep all samples. (Default: NULL)

collapse

Logical scalar. Should the features that do not meet the rows condition be merged into one feature instead of being removed? (Default: FALSE)

collapse.name

Character scalar. Name of the merged feature when collapse = TRUE. (Default: "Other")

...

additional arguments passed to agglomerateByVariable when collapse = TRUE, e.g. update.tree.

Value

x with the features and samples that meet the conditions.

Details

The expressions can refer to the assays by their names (e.g. counts), which are available as matrices. rows can also refer to the columns of rowData(x), and cols to the columns of colData(x). If an assay and a rowData or colData column have the same name, the assay is used. Other variables, such as thresholds, are taken from the environment where subsetBy is called.

rows is evaluated before cols, and cols is evaluated on the data that remains after subsetting the rows. NA values in the result of a condition are treated as FALSE.

With collapse = TRUE, the features that do not meet the rows condition are merged into a single feature named collapse.name, placed after the kept features. Its values are the sums of the merged features, so the sample totals stay the same. This is useful, for example, for plotting the most abundant features together with the rest. Summing is meaningful for counts and relative abundances but not for transformed values such as clr. The merging is done with agglomerateByVariable, which drops the rowTree unless update.tree = TRUE. collapse affects only features; samples that do not meet the cols condition are always removed.

See also

Examples

data(GlobalPatterns)
tse <- GlobalPatterns

# Keep features with more than 10 counts in total
tse_sub <- subsetBy(tse, rows = rowSums(counts) > 10)

# Filter in steps. Each step is computed from the data left by the
# previous step, so library sizes are calculated after the rare features
# have been removed.
tse_sub <- tse |>
    subsetBy(rows = rowSums(counts) > 10) |>
    subsetBy(rows = rowMeans(counts > 0) > 0.25) |>
    subsetBy(cols = colSums(counts) > 100000)

# Keep the features with a mean relative abundance above 1% and merge the
# rest into one feature called "Other"
tse <- transformAssay(tse, method = "relabundance")
tse_sub <- subsetBy(
    tse, rows = rowMeans(relabundance) > 0.01, collapse = TRUE)
tail(rownames(tse_sub))
#> [1] "550960" "158660" "331820" "189047" "98605"  "Other" 

# Combine different subsettings in a pipe: first remove samples with
# fewer than 500,000 reads, then keep the 5 most abundant features and
# merge the rest into "Other". The result can be plotted, e.g., with
# miaViz::plotBoxplot() or miaViz::plotAbundance().
tse_top <- GlobalPatterns |>
    subsetBy(cols = colSums(counts) >= 500000) |>
    transformAssay(method = "relabundance") |>
    subsetBy(rows = rank(-rowMeans(relabundance)) <= 5, collapse = TRUE)
dim(tse_top)
#> [1]  6 20
rownames(tse_top)
#> [1] "329744" "549656" "279599" "550960" "331820" "Other" 

# Plot the top features and "Other" by sample type
if( requireNamespace("miaViz", quietly = TRUE) ){
    miaViz::plotBoxplot(
        tse_top, assay.type = "relabundance",
        x = "SampleType", fill.by = "SampleType",
        facet.by = "rownames", scales = "free_y")
}


# Conditions can also use rowData and colData variables
tse_sub <- subsetBy(
    tse, rows = Kingdom == "Bacteria", cols = SampleType == "Feces")

# This includes quality control metrics stored with addQC(). Note that
# stored metrics are not updated when the data is subsetted, so in stepwise
# filtering, compute the metric in the condition or call addQC() again.
tse <- addQC(tse, by = "rows")
tse <- addQC(tse, by = "cols")
tse_sub <- subsetBy(tse, rows = sd > 0 & detected >= 3, cols = total > 1e6)

# Keep the top 10 features, i.e., the features with the highest mean
# abundance
tse_top <- subsetBy(tse, rows = rank(-mean) <= 10)

# Keep features that are abundant (over 1%) in at least one sample, or
# that have a median count above zero
tse_sub <- subsetBy(tse, rows = rowMaxs(relabundance) > 0.01)
tse_sub <- subsetBy(tse, rows = rowMedians(counts) > 0)

# Remove constant features, i.e., features with zero variance
tse_sub <- subsetBy(tse, rows = rowVars(counts) > 0)

# Standard deviation is on the scale of the data, e.g., clr
tse <- transformAssay(tse, method = "clr", pseudocount = 1)
tse_sub <- subsetBy(tse, rows = rowSds(clr) > 1)

# Keep features and samples with at most 10% missing values
tse_sub <- subsetBy(
    tse,
    rows = rowMeans(is.na(counts)) <= 0.1,
    cols = colMeans(is.na(counts)) <= 0.1)

# Keep rare features, i.e., features present in at most 50% of samples
tse_sub <- subsetBy(tse, rows = rowMeans(counts > 0) <= 0.5)

# Use a detection limit: keep features whose relative abundance is above
# 0.1% in more than 20% of samples
tse_sub <- subsetBy(tse, rows = rowMeans(relabundance > 0.001) > 0.2)

# Calculate prevalence in each sample type. Keep features that are
# prevalent in at least one sample type, so that group-specific features
# are not removed, e.g., before differential abundance analysis.
prev <- sapply(splitOn(tse, group = "SampleType"), getPrevalence)
tse_sub <- subsetBy(tse, rows = rowSums(prev > 0.5) > 0)

# Keep features that are rare in all sample types
tse_sub <- subsetBy(tse, rows = rowSums(prev > 0.5) == 0)