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
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/aggregateAcrossCells.R
\name{aggregateAcrossCells}
\alias{aggregateAcrossCells}
\alias{aggregateAcrossCells,SummarizedExperiment-method}
\alias{aggregateAcrossCells,SingleCellExperiment-method}
\title{Aggregate data across groups of cells}
\usage{
aggregateAcrossCells(x, ...)
\S4method{aggregateAcrossCells}{SummarizedExperiment}(
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
)
\S4method{aggregateAcrossCells}{SingleCellExperiment}(
x,
ids,
...,
subset.row = NULL,
subset.col = NULL,
use.altexps = FALSE,
use.dimred = TRUE,
dimred.stats = NULL,
suffix = FALSE,
subset_row = NULL,
subset_col = NULL,
use_altexps = NULL,
use_dimred = NULL
)
}
\arguments{
\item{x}{A \linkS4class{SingleCellExperiment} or \linkS4class{SummarizedExperiment}
containing one or more matrices of expression values to be aggregated;
possibly along with \code{\link{colData}}, \code{\link{reducedDims}} and \code{\link{altExps}} elements.}
\item{...}{For the generic, further arguments to be passed to specific methods.
For the SummarizedExperiment method, further arguments to be passed to \code{\link{summarizeAssayByGroup}}.
For the SingleCellExperiment method, arguments to be passed to the SummarizedExperiment method.}
\item{ids}{A factor (or vector coercible into a factor) specifying the group to which each cell in \code{x} belongs.
Alternatively, a \linkS4class{DataFrame} of such vectors or factors,
in which case each unique combination of levels defines a group.}
\item{statistics}{Character vector specifying the type of statistics to be computed, see \code{?\link{summarizeAssayByGroup}}.
If not specified, defaults to \code{"sum"}.}
\item{average}{Deprecated, specifies whether to compute the average - use \code{statistics="mean"} instead.
Only used if \code{statistics=NULL}.}
\item{suffix}{Logical scalar indicating whether to always suffix the assay name with the statistic type.}
\item{subset.row}{An integer, logical or character vector specifying the features to use.
If \code{NULL}, defaults to all features.}
\item{subset.col}{An integer, logical or character vector specifying the cells to use.
Defaults to all cells with non-\code{NA} entries of \code{ids}.}
\item{store.number}{String specifying the field of the output \code{\link{colData}} to store the number of cells in each group.
If \code{NULL}, nothing is stored.}
\item{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 \code{\link{colData}} to which it applies.
Alternatively, a single function can be supplied, see below for more details.}
\item{use.assay.type}{A character or integer vector specifying the assay(s) of \code{x} containing count matrices.}
\item{subset_row, subset_col, store_number, use_exprs_values, use_altexps, use_dimred, coldata_merge}{Soft deprecated equivalents to the arguments described above.}
\item{use.altexps}{Deprecated, use \code{\link{applySCE}} instead.}
\item{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.}
\item{dimred.stats}{A character vector specifying how the reduced dimensions should be aggregated by group.
This can be one or more of \code{"mean"} and \code{"median"}.}
}
\value{
A SummarizedExperiment of the same class of \code{x} is returned containing summed/averaged matrices
generated by \code{\link{summarizeAssayByGroup}} on all assays in \code{use.assay.type}.
Column metadata are also aggregated according to the rules in \code{coldata.merge}, see Details.
}
\description{
Sum counts or average expression values for each feature across groups of cells,
while also aggregating values in the \code{\link{colData}} and other fields in a SummarizedExperiment.
}
\details{
This function summarizes the assay values in \code{x} for each group in \code{ids} using \code{\link{summarizeAssayByGroup}}
while also aggregating metadata across cells in a \dQuote{sensible} manner.
This makes it useful for obtaining an aggregated \linkS4class{SummarizedExperiment} during an analysis session;
in contrast, \code{\link{summarizeAssayByGroup}} is more lightweight and is better for use inside other functions.
Aggregation of the \code{\link{colData}} is controlled using functions in \code{coldata.merge}.
This can either be:
\itemize{
\item 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., \code{\link{sum}} or \code{\link{median}} for numeric covariates,
or a function that takes the most abundant level for categorical factors.
\item 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 \code{coldata.merge} is \dQuote{unspecified} and handled as described below.
A list element can also be set to \code{FALSE}, in which case no aggregation is performed for the corresponding field.
\item \code{NULL}, in which case all fields are considered to be unspecified.
\item \code{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 \code{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 \code{statistics} is of length greater than 1 or \code{suffix=TRUE},
the names of all aggregated matrices are suffixed with their type of aggregate statistic.
If \code{ids} is a \linkS4class{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 \code{ids} column metadata field as well as in the column names.
If \code{x} is a \linkS4class{SingleCellExperiment}, entries of \code{\link{reducedDims}} specified by \code{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 \code{"mean"} or \code{"median"} (or both) with \code{dimred.stats}.
If \code{dimred.stats} is of length greater than 1 or \code{suffix=TRUE},
the name of each matrix in the output \code{\link{reducedDims}} is suffixed with the type of average.
If \code{x} is a SingleCellExperiment, any alternative Experiments are removed from the output object.
Users should call \code{\link{applySCE}} to repeat the same aggregation on the alternative Experiments if this is desired - see Examples.
}
\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,]
}
\seealso{
\code{\link{summarizeAssayByGroup}}, which does the heavy lifting at the assay level.
}
\author{
Aaron Lun
}
|
