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

View source: R/downsampleMatrix.R

Downsample a count matrix to a desired proportion, either on a whole-matrix or per-cell basis.

1 | ```
downsampleMatrix(x, prop, bycol = TRUE, sink = NULL)
``` |

`x` |
An integer or numeric matrix-like object containing counts. |

`prop` |
A numeric scalar or, if |

`bycol` |
A logical scalar indicating whether downsampling should be performed on a column-by-column basis. |

`sink` |
A RealizationSink object specifying the format of the downsampled matrix should be returned. |

Given multiple batches of very different sequencing depths, it can be beneficial to downsample the deepest batches to match the coverage of the shallowest batches. This avoids differences in technical noise that can drive clustering by batch.

If `bycol=TRUE`

, sampling without replacement is performed on the count vector for each cell.
This yields a new count vector where the total is equal to `prop`

times the original total count.
Each count in the returned matrix is guaranteed to be smaller than the original value in `x`

.
Different proportions can be specified for different cells by setting `prop`

to a vector;
in this manner, downsampling can be used as an alternative to scaling for per-cell normalization.

If `bycol=FALSE`

, downsampling without replacement is performed on the entire matrix.
This yields a new matrix where the total count across all cells is equal to `prop`

times the original total.
The new total count for each cell may not be exactly equal to `prop`

times the original value,
which may or may not be more appropriate than `bycol=TRUE`

for particular applications.

By default, the output format will be a dense matrix for an ordinary matrix `x`

,
and a sparse matrix for any sparse format (i.e., if `is_sparse(x)`

returns `TRUE`

).
This can be overridden to specify custom formats with `sink`

, e.g., for HDF5-backed matrices,
which may be helpful for dealing with large matrices where the downsampled result may not fit in memory.

Note that this function was originally implemented in the scater package as `downsampleCounts`

,
was moved to the DropletUtils package as `downsampleMatrix`

,
and finally found a home here.

An numeric matrix-like object of downsampled counts.
This is a dgCMatrix unless `sink`

is set, in which case it is a DelayedMatrix.

Aaron Lun

`downsampleReads`

in the DropletUtils package,
which downsamples reads rather than observed counts.

`normalizeCounts`

, where downsampling can be used as an alternative to scaling normalization.

1 2 3 4 5 6 7 8 | ```
sce <- mockSCE()
sum(counts(sce))
downsampled <- downsampleMatrix(counts(sce), prop = 0.5, bycol=FALSE)
sum(downsampled)
downsampled2 <- downsampleMatrix(counts(sce), prop = 0.5, bycol=TRUE)
sum(downsampled2)
``` |

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.