aggregateAcrossCells: Aggregate data across groups of cells

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

Description

Sum counts or average expression values for each feature across groups of cells, while also aggregating values in the colData and other fields in a SummarizedExperiment.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
aggregateAcrossCells(x, ...)

## S4 method for signature 'SummarizedExperiment'
aggregateAcrossCells(
  x,
  ids,
  ...,
  statistics = NULL,
  average = NULL,
  suffix = FALSE,
  subset.row = NULL,
  subset.col = NULL,
  store.number = "ncells",
  coldata.merge = NULL,
  use.assay.type = "counts",
  subset_row = NULL,
  subset_col = NULL,
  store_number = "ncells",
  coldata_merge = NULL,
  use_exprs_values = NULL
)

## S4 method for signature 'SingleCellExperiment'
aggregateAcrossCells(
  x,
  ids,
  ...,
  subset.row = NULL,
  subset.col = NULL,
  use.altexps = TRUE,
  use.dimred = TRUE,
  dimred.stats = NULL,
  suffix = FALSE,
  subset_row = NULL,
  subset_col = NULL,
  use_altexps = NULL,
  use_dimred = NULL
)

Arguments

x

A SingleCellExperiment or SummarizedExperiment containing one or more matrices of expression values to be aggregated; possibly along with colData, reducedDims and altExps elements.

...

For the generic, further arguments to be passed to specific methods.

For the SummarizedExperiment method, further arguments to be passed to summarizeAssayByGroup.

For the SingleCellExperiment method, arguments to be passed to the SummarizedExperiment method.

ids

A factor (or vector coercible into a factor) specifying the group to which each cell in x belongs. Alternatively, a DataFrame of such vectors or factors, in which case each unique combination of levels defines a group.

statistics

Character vector specifying the type of statistics to be computed, see ?summarizeAssayByGroup. If not specified, defaults to "sum".

average

Deprecated, specifies whether to compute the average - use statistics="mean" instead. Only used if statistics=NULL.

suffix

Logical scalar indicating whether to always suffix the assay name with the statistic type.

subset.row

An integer, logical or character vector specifying the features to use. If NULL, defaults to all features.

subset.col

An integer, logical or character vector specifying the cells to use. Defaults to all cells with non-NA entries of ids.

store.number

String specifying the field of the output colData to store the number of cells in each group. If NULL, nothing is stored.

coldata.merge

A named list of functions specifying how each column metadata field should be aggregated. Each function should be named according to the name of the column in colData to which it applies. Alternatively, a single function can be supplied, see below for more details.

use.assay.type

A character or integer vector specifying the assay(s) of x containing count matrices.

subset_row, subset_col, store_number, use_exprs_values, use_altexps, use_dimred, coldata_merge

Soft deprecated equivalents to the arguments described above.

use.altexps

Deprecated, use applySCE instead.

use.dimred

Logical scalar indicating whether aggregation should be performed for dimensionality reduction results. Alternatively, a character or integer vector specifying the dimensionality reduction results to be aggregated.

dimred.stats

A character vector specifying how the reduced dimensions should be aggregated by group. This can be one or more of "mean" and "median".

Details

This function summarizes the assay values in x for each group in ids using summarizeAssayByGroup while also aggregating metadata across cells in a “sensible” manner. This makes it useful for obtaining an aggregated SummarizedExperiment during an analysis session; in contrast, summarizeAssayByGroup is more lightweight and is better for use inside other functions.

Aggregation of the colData is controlled using functions in coldata.merge. This can either be:

For any unspecified field, we check if all cells of a group have the same value. If so, that value is reported, otherwise a NA is reported for the offending group.

By default, each matrix values is returned with the same name as the original per-cell matrix from which it was derived. If statistics is of length greater than 1 or suffix=TRUE, the names of all aggregated matrices are suffixed with their type of aggregate statistic.

If ids is a DataFrame, the combination of levels corresponding to each column is also reported in the column metadata. Otherwise, the level corresponding to each column is reported in the ids column metadata field as well as in the column names.

If x is a SingleCellExperiment, entries of reducedDims specified by use.dimred are averaged across cells. This assumes that the average of low-dimensional coordinates has some meaning for a group of cells but the sum does not. We can explicitly specify computation of the "mean" or "median" (or both) with dimred.stats. If dimred.stats is of length greater than 1 or suffix=TRUE, the name of each matrix in the output reducedDims is suffixed with the type of average.

Value

A SummarizedExperiment of the same class of x is returned containing summed/averaged matrices generated by summarizeAssayByGroup on all assays in use.assay.type. Column metadata are also aggregated according to the rules in coldata.merge, see below.

For the SingleCellExperiment method, any alternative Experiments are removed when use.altexps=NULL.

Author(s)

Aaron Lun

See Also

summarizeAssayByGroup, which does the heavy lifting at the assay level.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
example_sce <- mockSCE()
ids <- sample(LETTERS[1:5], ncol(example_sce), replace=TRUE)
out <- aggregateAcrossCells(example_sce, ids)
out

batches <- sample(1:3, ncol(example_sce), replace=TRUE)
out2 <- aggregateAcrossCells(example_sce, 
      DataFrame(label=ids, batch=batches))
out2

# Using another column metadata merge strategy.
example_sce$stuff <- runif(ncol(example_sce))
out3 <- aggregateAcrossCells(example_sce, ids, 
     coldata_merge=list(stuff=sum))

# Aggregating across the alternative Experiments as well.
out4 <- applySCE(example_sce, aggregateAcrossCells, ids=ids)
assay(altExp(out4))[1:10,]

LTLA/scuttle documentation built on Aug. 7, 2021, 5:06 a.m.