aggregateAcrossCells: Aggregate data across groups of cells
In scuttle: Single-Cell RNA-Seq Analysis Utilities

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

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.

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
)

`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. For the SingleCellExperiment method, this argument will not affect alternative Experiments, where aggregation is always performed for all features (or not at all, depending on `use.altexps`).
`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`	Logical scalar indicating whether aggregation should be performed for alternative experiments. Alternatively, a character or integer vector specifying the alternative experiments to be aggregated.
`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"`.

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:

A function that takes a subset of entries for any given column metadata field and returns a single value. This can be set to, e.g., sum or median for numeric covariates, or a function that takes the most abundant level for categorical factors.
A named list of such functions, where each function is applied to the column metadata field after which it is named. Any field that does not have an entry in coldata.merge is “unspecified” and handled as described below. A list element can also be set to FALSE, in which case no aggregation is performed for the corresponding field.
NULL, in which case all fields are considered to be unspecified.
FALSE, in which case no aggregation of column metadata is performed.

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.

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, the output also contains aggregated values for the reduced dimensions and alternative Experiments.

If x is a SingleCellExperiment, aggregation is repeated for each entry of altExps. This is done by calling aggregateAcrossCells on that entry with the same arguments used for the main Experiment - as such, any column metadata in those entries will also be aggregated following the rules in coldata.merge. The exception is subset.row, which is not applied to the alternative Experiments as the feature sets are different.

If x is a SingleCellExperiment, each entry of reducedDims is 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.

Users can tune the behavior of the function for these additional fields with use.altexps and use.dimred. Note that if the alternative experiments themselves are SingleCellExperiments, any further nested alternative experiment or reduced dimensions will always be aggregated regardless of the value of use.altexps or use.dimred.

Aaron Lun

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

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))
out3