aggregateAcrossCells {scuttle} | R Documentation

## Aggregate data across groups of cells

### 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

    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:

- 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.

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

    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,]

[Package scuttle version 1.2.1 Index]