Description Usage Arguments Details Value Consolidating with DE against any other cluster Consolidating with DE against all other clusters Consolidating with DE against some other clusters Consolidating against some other clusters, rankstyle Correcting for multiple testing Ordering of the output Author(s) References See Also Examples
View source: R/combineMarkers.R
Combine multiple pairwise differential expression comparisons between groups or clusters into a single ranked list of markers for each cluster.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 
de.lists 
A listlike object where each element is a data.frame or DataFrame. Each element should represent the results of a pairwise comparison between two groups/clusters, in which each row should contain the statistics for a single gene/feature. Rows should be named by the feature name in the same order for all elements. 
pairs 
A matrix, data.frame or DataFrame with two columns and number of rows equal to the length of 
pval.field 
A string specifying the column name of each element of 
effect.field 
A string specifying the column name of each element of 
pval.type 
A string specifying how pvalues are to be combined across pairwise comparisons for a given group/cluster. 
min.prop 
Numeric scalar specifying the minimum proportion of significant comparisons per gene,
Defaults to 0.5 when 
log.p.in 
A logical scalar indicating if the pvalues in 
log.p.out 
A logical scalar indicating if logtransformed pvalues/FDRs should be returned. 
output.field 
A string specifying the prefix of the field names containing the effect sizes.
Defaults to 
full.stats 
A logical scalar indicating whether all statistics in 
sorted 
Logical scalar indicating whether each output DataFrame should be sorted by a statistic relevant to 
flatten 
Logical scalar indicating whether the individual effect sizes should be flattened in the output DataFrame.
If 
BPPARAM 
A BiocParallelParam object indicating whether and how parallelization should be performed across genes. 
An obvious strategy to characterizing differences between clusters is to look for genes that are differentially expressed (DE) between them.
However, this entails a number of comparisons between all pairs of clusters to comprehensively identify genes that define each cluster.
For all pairwise comparisons involving a single cluster, we would like to consolidate the DE results into a single list of candidate marker genes.
Doing so is the purpose of the combineMarkers
function.
DE statistics from any testing regime can be supplied to this function  see the Examples for how this is done with ttests from pairwiseTTests
.
The effect size field in the output will vary according to the type of input statistics, for example:
logFC.Y
from pairwiseTTests
, containing logfold changes in mean expression (usually in base 2).
AUC.Y
from pairwiseWilcox
, containing the area under the curve, i.e., the concordance probability.
logFC.Y
from pairwiseBinom
, containing log2fold changes in the expressing proportion.
A named List of DataFrames where each DataFrame contains the consolidated marker statistics for each gene (row) for the cluster of the same name. The DataFrame for cluster X contains the fields:
Top
:Integer, the minimum rank across all pairwise comparisons.
This is only reported if pval.type="any"
.
p.value
:Numeric, the combined pvalue across all comparisons if log.p.out=FALSE
.
FDR
:Numeric, the BHadjusted pvalue for each gene if log.p.out=FALSE
.
log.p.value
:Numeric, the (natural) logtransformed version pvalue.
Replaces the p.value
field if log.p.out=TRUE
.
log.FDR
:Numeric, the (natural) logtransformed adjusted pvalue.
Replaces the FDR
field if log.p.out=TRUE
.
summary.<OUTPUT>
:Numeric, named by replacing <OUTPUT>
with output.field
.
This contains the summary effect size, obtained by combining effect sizes from all pairwise comparison into a single value.
Only reported when effect.field
is not NULL
.
<OUTPUT>.Y
:Comparisonspecific statistics, named by replacing <OUTPUT>
with output.field
.
One of these fields is present for every other cluster Y in clusters
and contains statistics for the comparison of X to Y.
If full.stats=FALSE
, each field is numeric and contains the effect size of the comparison of X over Y.
Otherwise, each field is a nested DataFrame containing the full statistics for that comparison (i.e., the same asthe corresponding entry of de.lists
).
Only reported if flatten=FALSE
and (for full.stats=FALSE
) if effect.field
is not NULL
.
each.<OUTPUT>
:A nested DataFrame of comparisonspecific statistics, named by replacing <OUTPUT>
with output.field
.
If full.stats=FALSE
, one column is present for every other cluster Y in clusters
and contains the effect size of the comparison of X to Y.
Otherwise, each column contains another nested DataFrame containing the full set of statistics for that comparison.
Only reported if flatten=FALSE
and (for full.stats=FALSE
) if effect.field
is not NULL
.
By default, each DataFrame is sorted by the Top
value when pval.type="any"
.
Taking all rows with Top
values less than or equal to T yields a marker set containing the top T genes (ranked by significance) from each pairwise comparison.
This guarantees the inclusion of genes that can distinguish between any two clusters.
To demonstrate, let us define a marker set with an T of 1 for a given cluster.
The set of genes with Top <= 1
will contain the top gene from each pairwise comparison to every other cluster.
If T is instead, say, 5, the set will consist of the union of the top 5 genes from each pairwise comparison.
Obviously, multiple genes can have the same Top
as different genes may have the same rank across different pairwise comparisons.
Conversely, the marker set may be smaller than the product of Top
and the number of other clusters, as the same gene may be shared across different comparisons.
This approach does not explicitly favour genes that are uniquely expressed in a cluster.
Rather, it focuses on combinations of genes that  together  drive separation of a cluster from the others.
This is more general and robust but tends to yield a less focused marker set compared to the other pval.type
settings.
For each gene and cluster, the summary effect size is defined as the effect size from the pairwise comparison with the lowest pvalue. The combined pvalue is computed by applying Simes' method to all pvalues. Neither of these values are directly used for ranking and are only reported for the sake of the user.
If pval.type="all"
, the null hypothesis is that the gene is not DE in all contrasts.
A combined pvalue for each gene is computed using Berger's intersection union test (IUT).
Ranking based on the IUT pvalue will focus on genes that are DE in that cluster compared to all other clusters.
This strategy is particularly effective when dealing with distinct clusters that have a unique expression profile.
In such cases, it yields a highly focused marker set that concisely captures the differences between clusters.
However, it can be too stringent if the cluster's separation is driven by combinations of gene expression.
For example, consider a situation involving four clusters expressing each combination of two marker genes A and B.
With pval.type="all"
, neither A nor B would be detected as markers as it is not uniquely defined in any one cluster.
This is especially detrimental with overclustering where an otherwise acceptable marker is discarded if it is not DE between two adjacent clusters.
For each gene and cluster, the summary effect size is defined as the effect size from the pairwise comparison with the largest pvalue. This reflects the fact that, with this approach, a gene is only as significant as its weakest DE. Again, this value is not directly used for ranking and are only reported for the sake of the user.
The pval.type="some"
setting serves as a compromise between "all"
and "any"
.
A combined pvalue is calculated by taking the middlemost value of the Holmcorrected pvalues for each gene.
(By default, this the median for odd numbers of contrasts and oneafterthemedian for even numbers, but the exact proportion can be changed by setting min.prop
 see ?combinePValues
.)
Here, the null hypothesis is that the gene is not DE in at least half of the contrasts.
Genes are then ranked by the combined pvalue.
The aim is to provide a more focused marker set without being overly stringent, though obviously it loses the theoretical guarantees of the more extreme settings.
For example, there is no guarantee that the top set contains genes that can distinguish a cluster from any other cluster, which would have been possible with pval.type="any"
.
For each gene and cluster, the summary effect size is defined as the effect size from the pairwise comparison with the min.prop
smallest pvalue.
This mirrors the pvalue calculation but, again, is reported only for the benefit of the user.
A slightly different flavor of the “some cluster” approach is achieved by setting method="any"
with min.prop
set to some positive value in (0, 1).
A gene will only be highranked if it is among the topranked genes in at least min.prop
of the pairwise comparisons.
For example, if min.prop=0.3
, any gene with a value of Top
less than or equal to 5 will be in the top 5 DEGs of at least 30
This method increases the stringency of the "any"
setting in a safer manner than pval.type="some"
.
Specifically, we avoid comparing pvalues across pairwise comparisons, which can be problematic if there are power differences across comparisons, e.g., due to differences in the number of cells across the other clusters.
Note that the value of min.prop
does not affect the combined pvalue and summary effect size calculations for pval.type="any"
.
The BH method is then applied on the consolidated pvalues across all genes to obtain the FDR
field.
The reported FDRs are intended only as a rough measure of significance.
Properly correcting for multiple testing is not generally possible when clusters
is determined from the same x
used for DE testing.
If log.p=TRUE
, logtransformed pvalues and FDRs will be reported.
This may be useful in overpowered studies with many cells, where directly reporting the raw pvalues would result in many zeroes due to the limits of machine precision.
Within each DataFrame, if sorted=TRUE
, genes are ranked by the Top
column if available and the p.value
(or log.p.value
) if not.
Otherwise, the input order of the genes is preserved.
For the DataFrame corresponding to cluster X, the <OUTPUT>.Y
columns are sorted according to the order of cluster IDs in pairs[,2]
for all rows where pairs[,1]
is X.
In the output List, the DataFrames themselves are sorted according to the order of cluster IDs in pairs[,1]
.
Note that DataFrames are only created for clusters present in pairs[,1]
.
Clusters unique to pairs[,2]
will only be present within a DataFrame as Y.
Aaron Lun
Simes RJ (1986). An improved Bonferroni procedure for multiple tests of significance. Biometrika 73:751754.
Berger RL and Hsu JC (1996). Bioequivalence trials, intersectionunion tests and equivalence confidence sets. Statist. Sci. 11, 283319.
pairwiseTTests
and pairwiseWilcox
, for functions that can generate de.lists
and pairs
.
findMarkers
, which automatically performs combineMarkers
on the ttest or Wilcoxon test results.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19  library(scuttle)
sce < mockSCE()
sce < logNormCounts(sce)
# Any clustering method is okay.
kout < kmeans(t(logcounts(sce)), centers=3)
clusters < paste0("Cluster", kout$cluster)
out < pairwiseTTests(logcounts(sce), groups=clusters)
comb < combineMarkers(out$statistics, out$pairs)
comb[["Cluster1"]]
out < pairwiseWilcox(logcounts(sce), groups=clusters)
comb < combineMarkers(out$statistics, out$pairs, effect.field="AUC")
comb[["Cluster2"]]
out < pairwiseBinom(logcounts(sce), groups=clusters)
comb < combineMarkers(out$statistics, out$pairs)
comb[["Cluster3"]]

Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.