downsampleBatches: Downsample batches to equal coverage
In scuttle: Single-Cell RNA-Seq Analysis Utilities

Description Usage Arguments Details Value Author(s) See Also Examples

A convenience function to downsample all batches so that the average per-cell total count is the same across batches. This mimics the downsampling functionality of cellranger aggr.

downsampleBatches(
  ...,
  batch = NULL,
  block = NULL,
  method = c("median", "mean", "geomean"),
  bycol = TRUE,
  assay.type = 1
)

`...`	Two or more count matrices, where each matrix has the same set of genes (rows) and contains cells (columns) from a separate batch. Alternatively, one or more entries may be a SummarizedExperiment, in which case the count matrix is extracted from the assays according to `assay.type`. A list containing two or more of these matrices or SummarizedExperiments can also be supplied. Alternatively, a single count matrix or SummarizedExperiment can be supplied. This is assumed to contain cells from all batches, in which case `batch` should also be specified.
`batch`	A factor of length equal to the number of columns in the sole entry of `...`, specifying the batch of origin for each column of the matrix. Ignored if there are multiple entries in `...`.
`block`	If `...` contains multiple matrices or SummarizedExperiments, this should be a character vector of length equal to the number of objects in `...`, specifying the blocking level for each object (see Details). Alternatively, if `...` contains a single object, this should be a character vector or factor of length specifing the blocking level for each cell in that object.
`method`	String indicating how the average total should be computed. The geometric mean is computed with a pseudo-count of 1.
`bycol`	A logical scalar indicating whether downsampling should be performed on a column-by-column basis, see `?downsampleMatrix` for more details.
`assay.type`	String or integer scalar specifying the assay of the SummarizedExperiment containing the count matrix, if any SummarizedExperiments are present in `...`.

Downsampling batches with strong differences in sequencing coverage can make it easier to compare them to each other, reducing the burden on the normalization and batch correction steps. This is especially true when the number of cells cannot be easily controlled across batches, resulting in large differences in per-cell coverage even when the total sequencing depth is the same.

Generally speaking, the matrices in ... should be filtered so that only libraries with cells are present. This is most relevant to high-throughput scRNA-seq experiments (e.g., using droplet-based protocols) where the majority of libaries do not actually contain cells. If these are not filtered out, downsampling will equalize coverage among the majority of empty libraries rather than among cell-containing libraries.

In more complex experiments, batches can be organized into blocks where downsampling is performed to the lowest-coverage batch within each block. This is most useful for larger datasets involving technical replicates for the same biological sample. By setting block= to the biological sample, we can equalize coverage across replicates within each sample without forcing all samples to have the same coverage (e.g., to avoid loss of information if they are to be analyzed separately anyway).

If ... contains two or more matrices, a List of downsampled matrices is returned.

Otherwise, if ... contains only one matrix, the downsampled matrix is returned directly.

Aaron Lun

downsampleMatrix, which is called by this function under the hood.

sce1 <- mockSCE()
sce2 <- mockSCE()

# Downsampling for multiple batches in a single matrix:
combined <- cbind(sce1, sce2)
batches <- rep(1:2, c(ncol(sce1), ncol(sce2)))
downsampled <- downsampleBatches(counts(combined), batch=batches)
downsampled[1:10,1:10]

# Downsampling for multiple matrices:
downsampled2 <- downsampleBatches(counts(sce1), counts(sce2))
downsampled2