dsea: Differential set enrichment from a design

View source: R/dsea_pathway.R

dseaR Documentation

Differential set enrichment from a design

Description

dsea() takes counts and a design and returns GSEA results for a contrast: it transforms the counts, reduces the design to a per-gene statistic, ranks the genes and runs the GSEA engine. dsea_scores() stops one step earlier and returns the gene set by sample score matrix instead.

Usage

dsea(
  x,
  gene_sets,
  design,
  contrast = NULL,
  transform = c("vst", "rlog"),
  min_size = 10L,
  max_size = 500L,
  ...
)

dsea_scores(
  x,
  gene_sets,
  transform = c("vst", "rlog", "logcpm"),
  min_size = 10L,
  max_size = 500L,
  exponent = 1,
  ...
)

Arguments

x

a counts matrix, or a DESeqDataSet.

gene_sets

a named list of gene identifier vectors, identifiers matching rownames(x).

design

for dsea(): an ⁠n x p⁠ design matrix from model.matrix(), row-aligned with the samples. Must be full rank.

contrast

a column name or index of design. Defaults to the only non-intercept column of a two-column design; a wider design must name the contrast explicitly, because the useful column cannot be guessed.

transform

"vst" (default) or "rlog"; dsea_scores() also accepts "logcpm".

min_size, max_size

gene set size limits, applied to the overlap with the genes actually present.

...

for dsea(), passed to gsea().

exponent

for dsea_scores(): rank weighting passed to ssgsea_scores().

Details

Why the ranking is what it is. Genes are ranked by the difference in mean transformed expression between the two sides of the contrast. That looks like the weakest available choice and it is the one the benchmark supported: ranking by a moderated t or by DESeq2's Wald statistic was no better under uniform or heterogeneous effects, and materially worse when the affected genes were the noisier ones (recall 0.826 for Wald against 0.979 for the mean difference under an eightfold dispersion multiplier; across a 1x/2x/4x series the Wald statistic falls 0.995 to 0.950 while the mean difference stays flat). GSEA's statistic already equalises genes by rank, so layering a variance weight on top discards real signal at the extremes rather than adding power.

Which column may be the contrast. A design column encodes a comparison only when it is not constant and not a group indicator under cell-means coding. The intercept is rejected because ranking by it orders genes by mean expression, which turns the analysis into "highly expressed pathways"; a column of ~ 0 + condition is rejected for the same reason, since its coefficient is one group's mean rather than a difference. A continuous column (a dose slope, say) is allowed.

The transform uses design(x), the ranking uses design. When x is a DESeqDataSet, vst(blind = FALSE) reads the design stored in the object, while the ranking reads the design argument. If the two differ the call warns rather than blending two models: refit the object with the intended design, or pass a counts matrix so the transform can use design.

What the design is used for. For a two-group contrast the ranking is the group mean difference. For a design with nuisance terms it is the contrast coefficient from the fitted linear model, so batch and other covariates are removed before ranking rather than ignored.

What this is not. It is a design-aware front end to GSEA, not a new set test. Directions are relative to the ranking: a set scoring high sits toward the top, which is the direction the contrast was oriented in.

Value

dsea() returns the data.frame from gsea(), sorted by p-value, with two columns added: padj, the Benjamini-Hochberg adjusted p-value, and contrast, the design column that was tested. Everything else is GSEA's own output, so the table can be filtered and plotted like any other GSEA result.

dsea_scores() returns a list with scores (gene sets by samples) and meta recording the transform and scorer settings. meta$set_sizes reports the number of members actually scored, after intersecting with the data, and meta$raw_set_sizes the input size, so the two can be compared.

See Also

gsea, ssgsea_scores

Examples

## Not run: 
dds <- DESeq2::DESeq(DESeq2::DESeqDataSetFromMatrix(counts, coldata, ~ condition))
design <- model.matrix(~ condition, coldata)
res <- dsea(dds, gene_sets, design = design, contrast = "conditionB")
head(res[order(res$pvalue), ])

sc <- dsea_scores(dds, gene_sets)
dim(sc$scores)

## End(Not run)

enrichit documentation built on Oct. 28, 2026, 9:07 a.m.