Nothing
#' Gene Set Enrichment Analysis (GSEA)
#'
#' Perform Gene Set Enrichment Analysis (GSEA) using a ranked gene list.
#'
#' @inheritParams enrichit_params
#' @param weight A named numeric vector of weights for genes. The names should match the names of geneList. If provided, the geneList will be multiplied by the weight and resorted before GSEA (default: NULL).
#' @param eps Epsilon for multilevel methods (default: 1e-10). Sets the smallest p-value that can be estimated.
#' @param sampleSize Sample size for multilevel methods (default: 101).
#' @param seed Random seed for reproducibility (default: FALSE). Set to a number to make
#' the result reproducible; set to TRUE to use a fixed default seed. If FALSE (default),
#' a seed is drawn from R's random number generator on each run, so results may vary
#' between runs. Note that the C++ engine uses its own RNG seeded with this value:
#' passing an explicit numeric seed (or calling \code{set.seed()} before \code{gsea()}
#' when \code{seed = FALSE}) makes the result reproducible.
#' @param nPermSimple Number of permutations for the simple method (default: 1000).
#' @param scoreType Type of enrichment score calculation: "std", "pos", "neg" (default: "std").
#' Only honoured by \code{method = "multilevel"}; fixed and adaptive
#' permutation paths currently use the standard two-sided score.
#'
#' @return A data.frame with columns:
#' - **ID**: Gene set name
#' - **enrichmentScore**: Enrichment Score
#' - **NES**: Normalized Enrichment Score
#' - **pvalue**: Empirical p-value from the permutation test. With the default
#' two-sided \code{scoreType = "std"}, the denominator counts only
#' permutations on the same side of zero as the observed ES (fgsea
#' convention). The \code{"pos"}/\code{"neg"} score types are supported by
#' the multilevel engine; fixed and adaptive permutation paths currently use
#' the two-sided ES calculation. For fixed or adaptive permutation runs,
#' the smallest estimable p-value is determined by the number of same-side
#' null permutations, not by the total number of permutations.
#' - **setSize**: Size of the gene set (number of genes found in geneList)
#' - **nPerm**: (adaptive mode only) Actual number of permutations used
#' - **rank**: Rank at which the maximum enrichment score is attained
#' - **leading_edge**: Leading edge statistics (tags, list, signal)
#' - **core_enrichment**: Genes in the leading edge, separated by '/'
#'
#' @examples
#' # Example data
#' stats <- rnorm(1000)
#' names(stats) <- paste0("Gene", 1:1000)
#' stats <- sort(stats, decreasing = TRUE)
#'
#' gs1 <- paste0("Gene", 1:50)
#' gs2 <- paste0("Gene", 500:550)
#' gene_sets <- list(Pathway1 = gs1, Pathway2 = gs2)
#'
#' # Use default fixed permutation method
#' result <- gsea(geneList=stats, gene_sets=gene_sets, nPerm=100)
#'
#' # Use adaptive permutation for more accurate p-values
#' \donttest{
#' result_adaptive <- gsea(geneList=stats, gene_sets=gene_sets, adaptive=TRUE)
#' }
#'
#' @export
gsea <- function(geneList, gene_sets,
weight = NULL,
minGSSize = 10,
maxGSSize = 500,
nPerm = 1000,
exponent = 1.0,
method = "multilevel",
adaptive = FALSE,
minPerm = 101,
maxPerm = 100000,
pvalThreshold = 0.1,
eps = 1e-10,
sampleSize = 101,
seed = FALSE,
nPermSimple = 1000,
scoreType = "std",
verbose = TRUE) {
gene_sets <- validate_gene_sets(gene_sets)
if (!is.null(weight)) {
if (!is.numeric(weight) || is.null(names(weight))) {
stop("weight must be a named numeric vector")
}
common_genes <- intersect(names(geneList), names(weight))
if (length(common_genes) == 0) {
stop("No common genes found between geneList and weight")
}
if (verbose && length(common_genes) < length(geneList)) {
message("Weight provided: ", length(common_genes), " out of ", length(geneList), " genes are weighted.")
}
geneList <- geneList[common_genes]
weight_aligned <- weight[common_genes]
if (any(weight_aligned < 0, na.rm = TRUE)) {
warning("Negative weights detected. Taking absolute values.")
weight_aligned <- abs(weight_aligned)
}
# Apply weight
geneList <- geneList * weight_aligned
# Re-sort to maintain preranked requirement
geneList <- sort(geneList, decreasing = TRUE)
}
method <- match.arg(method, c("sample", "permute", "multilevel"))
scoreType <- match.arg(scoreType, c("std", "pos", "neg"))
## `eps` is the smallest p-value the multilevel method can estimate, not a
## tolerance, so a value above 1 puts the floor above every possible p-value:
## any pathway that reaches the multilevel refinement comes back with p = eps,
## i.e. p > 1, which then propagates into p.adjust() and -log10() in plots.
## Upstream fgsea clamps silently; erroring is more useful than returning a
## p-value that cannot exist (measured: eps = 2 gave p = 2, 2026-10-27).
if (!is.numeric(eps) || length(eps) != 1L || is.na(eps) || eps < 0 || eps > 1) {
stop("`eps` must be a single number in [0, 1]; it is the smallest p-value ",
"the multilevel method can estimate. Set eps = 0 for the best estimate.",
call. = FALSE)
}
if (scoreType != "std" && method != "multilevel") {
warning(
"scoreType = \"", scoreType, "\" is only supported by method = \"multilevel\"; ",
"method = \"", method, "\" uses the standard two-sided ES calculation."
)
}
prepared <- prepare_gsea_inputs(geneList, scoreType, exponent)
geneList <- prepared$geneList
multilevelRanks <- prepared$multilevelRanks
sampleSize <- normalize_multilevel_sample_size(sampleSize)
# seed semantics: a numeric (or TRUE -> fixed default seed) makes the result
# reproducible; FALSE draws a fresh seed from R's RNG on each run, so results
# may differ between runs (inherent to permutation-based GSEA). Note that the
# C++ engine seeds its own RNG with this value, so passing an explicit seed
# (or set.seed() before the call when seed = FALSE) fixes the result.
if (isTRUE(seed)) {
seed <- 12345L # fixed default seed, consistent with the C++ default
} else if (isFALSE(seed)) {
seed <- sample.int(1e9, 1)
}
# Intersect with geneList to get overlapping genes;
# minGSSize/maxGSSize should constrain the overlap, not the raw set size
# see https://github.com/YuLab-SMU/clusterProfiler/issues/824
gene_sets <- filter_gene_sets(gene_sets, names(geneList))
# Filter by size
idx <- get_geneSet_index(gene_sets, minGSSize, maxGSSize)
if (sum(idx) == 0) {
if (verbose) {
msg <- paste("No gene sets have size between", minGSSize, "and", maxGSSize, "...")
message(msg)
message("--> return NULL...")
}
return (NULL)
}
gene_sets <- gene_sets[idx]
## A gene set that covers the entire ranked list has no "not in set" positions,
## so its running score never falls back and the enrichment score is undefined:
## the engine built the score with diff = n - k = 0 and returned ES/NES/pvalue
## all NaN, while the NA warning blamed "unbalanced gene-level statistic
## values" -- the wrong cause. fgsea excludes these sets through its default
## maxSize = length(stats) - 1; do the same, and say so, instead of shipping a
## NaN row (measured 2026-10-27: fgsea returned 1 row where enrichit returned
## that row plus an all-NaN set).
n_ranked <- length(geneList)
covers_all <- lengths(gene_sets) >= n_ranked
if (any(covers_all)) {
if (verbose) {
message(
"Excluding ", sum(covers_all), " gene set(s) that cover the entire ",
"ranked list (", n_ranked, " genes); their enrichment score is undefined."
)
}
gene_sets <- gene_sets[!covers_all]
if (length(gene_sets) == 0) {
if (verbose) message("--> return NULL...")
return(NULL)
}
}
gene_set_names <- names(gene_sets)
# Call appropriate C++ function
if (method == "multilevel") {
result <- gsea_multilevel_cpp(geneList = multilevelRanks, gene_sets = gene_sets, gene_set_names = gene_set_names,
minPerm = minPerm, maxPerm = maxPerm, pvalThreshold = pvalThreshold,
exponent = 1.0, method = method, eps = eps, sampleSize = sampleSize, seed = seed,
nPermSimple = nPermSimple, scoreType = scoreType)
} else if (adaptive) {
result <- gsea_adaptive_cpp(geneList, gene_sets, gene_set_names,
minPerm, maxPerm, pvalThreshold, exponent, method, seed)
} else {
result <- gsea_cpp(geneList, gene_sets, gene_set_names, nPerm, exponent, method, seed)
}
# Rename columns to standard names
if (!"ID" %in% names(result) && "GeneSet" %in% names(result)) names(result)[names(result) == "GeneSet"] <- "ID"
if (!"enrichmentScore" %in% names(result) && "ES" %in% names(result)) names(result)[names(result) == "ES"] <- "enrichmentScore"
if (!"pvalue" %in% names(result) && "PValue" %in% names(result)) names(result)[names(result) == "PValue"] <- "pvalue"
if (!"setSize" %in% names(result) && "Size" %in% names(result)) names(result)[names(result) == "Size"] <- "setSize"
# Add setSize if missing
if (!"setSize" %in% names(result)) {
# Calculate size based on gene_sets (filtered)
# Note: gene_sets order must match result ID order
# Assuming result ID matches gene_set_names order passed to C++
# If C++ preserves order (it does), we can map
set_sizes <- sapply(gene_sets, length)
result$setSize <- set_sizes[result$ID]
}
# Add NES if missing (placeholder)
if (!"NES" %in% names(result)) {
result$NES <- NA
}
if (!all(c("rank", "leading_edge", "core_enrichment") %in% names(result))) {
ledge_rank <- integer(nrow(result))
ledge_str <- character(nrow(result))
ledge_core <- character(nrow(result))
for (i in seq_len(nrow(result))) {
sid <- result$ID[[i]]
gs <- gene_sets[[sid]]
ledge <- gsea_leading_edge_details(geneList, gs, exponent = exponent, scoreType = scoreType)
ledge_rank[[i]] <- ledge$rank
ledge_str[[i]] <- ledge$leading_edge
ledge_core[[i]] <- ledge$core_enrichment
}
if (!"rank" %in% names(result)) result$rank <- ledge_rank
if (!"leading_edge" %in% names(result)) result$leading_edge <- ledge_str
if (!"core_enrichment" %in% names(result)) result$core_enrichment <- ledge_core
}
# Sort by absolute NES (descending) or pvalue (ascending)
if (nrow(result) > 0) {
if (!all(is.na(result$NES))) {
result <- result[order(abs(result$NES), decreasing = TRUE), ]
} else {
result <- result[order(result$pvalue, decreasing = FALSE), ]
}
}
if (method == "multilevel" && any(is.na(result$pvalue))) {
warning(
"There were ", sum(is.na(result$pvalue)),
" pathways for which P-values were not calculated properly; pvalue, NES ",
"and log2err are set to NA for them. The usual cause is an unbalanced ",
"gene-level statistic (no genes on one side of the ranking), which makes ",
"the permutation null degenerate; a gene set covering the whole ranked ",
"list is excluded before this point. You can try to increase nPermSimple, ",
"or pass reportNA = TRUE to keep these rows.",
call. = FALSE
)
}
if (method == "multilevel" && any(!is.na(result$pvalue) & result$pvalue == eps & is.na(result$log2err))) {
warning(
"For some pathways, in reality P-values are less than ", eps,
". You can set the eps argument to zero for better estimation."
)
}
return(result)
}
normalize_multilevel_sample_size <- function(sampleSize) {
sampleSize <- as.integer(sampleSize[[1]])
if (!is.finite(sampleSize)) {
stop("sampleSize must be a finite integer")
}
sampleSize <- max(sampleSize, 3L)
if (sampleSize %% 2L == 0L) {
sampleSize <- sampleSize + 1L
}
sampleSize
}
prepare_gsea_inputs <- function(geneList, scoreType, exponent) {
if (!is.numeric(geneList) || is.null(names(geneList))) {
stop("geneList must be a named numeric vector")
}
if (any(!is.finite(geneList))) {
stop("Not all stats values are finite numbers")
}
## An all-zero ranking has no order, so every enrichment score is undefined.
## It used to reach the engine: `scale_fgsea_ranks()` computed 2^30 / 0 = Inf,
## every rank became NA, and the multilevel path returned a full table of
## ES = NaN with no error -- a silently useless result that looks like an
## ordinary answer to anyone who does not inspect enrichmentScore
## (measured 2026-10-27).
if (!any(geneList != 0)) {
stop("All gene-level statistics are zero, so the ranking has no order and ",
"no enrichment score is defined. Check that the statistic was not ",
"lost or centred away upstream.", call. = FALSE)
}
if (isTRUE(is.unsorted(rev(geneList)))) {
warning("geneList is not sorted in descending order. Sorting it now.")
geneList <- sort(geneList, decreasing = TRUE)
}
ties <- sum(duplicated(geneList[geneList != 0]))
if (ties != 0) {
warning(
"There are ties in the preranked stats (",
round(ties * 100 / length(geneList), digits = 2),
"% of the list). The order of those tied genes will be arbitrary, which may produce unexpected results."
)
}
if (all(geneList > 0) && scoreType == "std") {
warning(
"All values in the stats vector are greater than zero and scoreType is \"std\", maybe you should switch to scoreType = \"pos\"."
)
}
multilevelRanks <- scale_fgsea_ranks(geneList, exponent)
list(
geneList = geneList,
multilevelRanks = multilevelRanks
)
}
#' Drop gene sets whose p-value could not be estimated
#'
#' Rows dropped here are invisible in the returned object, so the count is
#' reported: an `NA` p-value comes from the multilevel engine declining to
#' estimate (degenerate permutation null) rather than from a filter the caller
#' asked for, and a silently shorter table reads as "these were the only gene
#' sets tested". Extracted from `gsea_gson()` so the message can be tested
#' without having to construct an input whose null is degenerate.
#'
#' @param res a GSEA result data.frame, or NULL
#' @param reportNA keep the NA rows instead of dropping them
#' @return `res`, with NA-p-value rows removed when `reportNA` is FALSE
#' @noRd
.gsea_drop_na_rows <- function(res, reportNA) {
if (isTRUE(reportNA) || is.null(res) || nrow(res) == 0L) {
return(res)
}
n_na <- sum(is.na(res$pvalue))
if (n_na > 0) {
warning(
n_na, " of ", nrow(res),
" gene set(s) have no estimable p-value and were dropped ",
"(pvalue, NES and log2err are NA for them). Pass ",
"reportNA = TRUE to keep them, or raise nPermSimple.",
call. = FALSE
)
}
res[!is.na(res$pvalue), , drop = FALSE]
}
scale_fgsea_ranks <- function(geneList, exponent) {
ranks <- abs(geneList)^exponent
# Mirror fgsea::prepareStats(): scale to integer-like values based on the
# total weight rather than a fixed multiplier, which keeps the multilevel
# backend numerically closer to the long-used fgsea implementation.
#
# The total can only be 0 for an all-zero ranking, which `prepare_gsea_inputs()`
# rejects before reaching here; the guard keeps a direct caller from turning
# the whole vector into NA through 2^30 / 0 = Inf.
total <- sum(ranks)
if (!is.finite(total) || total <= 0) {
stop("Cannot scale the ranked statistic: the total weight is ", total,
" (all statistics are zero).", call. = FALSE)
}
scaleCoeff <- 2^30 / total
if (scaleCoeff >= 1) {
scaleCoeff <- floor(scaleCoeff)
}
ranks <- round(ranks * scaleCoeff)
storage.mode(ranks) <- "integer"
structure(ranks, names = names(geneList))
}
#' generic function for gene set enrichment analysis
#'
#'
#' @title gsea_gson
#' @inheritParams enrichit_params
#' @param weight A named numeric vector of weights for genes.
#' @param seed Random seed for reproducibility. See \code{gsea()} for details
#' (default: FALSE).
#' @param pvalueCutoff P-value cutoff applied to both the raw p-value and the
#' adjusted p-value (\code{p.adjust}), consistent with the historical
#' clusterProfiler/DOSE behavior (default: 0.05).
#' @param reportNA If \code{TRUE}, pathways with \code{NA} p-values (produced
#' by the multilevel method when gene-level statistics are unbalanced) are
#' retained in the result. Useful with \code{pvalueCutoff = 1} to inspect
#' the complete set of tested pathways. Default: \code{FALSE}, which
#' excludes \code{NA} rows from the reported result.
#' @param ... Additional parameters passed to gsea()
#' @return A `gseaResult` object. The `result` slot carries the three
#' significance columns `pvalue`, `p.adjust`, and `qvalue`:
#' raw nominal p-values, BH-style multiple-testing adjusted p-values
#' (via `stats::p.adjust()`; default `pAdjustMethod = "BH"`), and
#' Storey q-values (via `qvalue::qvalue()`). If q-value estimation
#' fails, `qvalue` remains `NA`. See `?as_gseaResult` for the full
#' column semantics.
#' @author Guangchuang Yu
#' @export
gsea_gson <- function(geneList,
gson,
weight = NULL,
nPerm = 1000,
exponent = 1.0,
minGSSize = 10,
maxGSSize = 500,
pvalueCutoff = 0.05,
pAdjustMethod = "BH",
method = "multilevel",
adaptive = FALSE,
minPerm = 101,
maxPerm = 100000,
pvalThreshold = 0.1,
seed = FALSE,
verbose = TRUE,
reportNA = FALSE,
...) {
if (!inherits(gson, "GSON")) {
stop("gson should be a GSON object")
}
# Ensure geneList is sorted.
# `isTRUE()` matters: with NA/NaN in geneList `is.unsorted()` returns NA, and a
# bare `if (NA)` aborts with "missing value where TRUE/FALSE needed" *before*
# the finiteness check in prepare_gsea_inputs() can report the real problem.
if (isTRUE(is.unsorted(rev(geneList)))) {
if (verbose) {
warning("geneList is not sorted in descending order. Sorting it now.")
}
geneList <- sort(geneList, decreasing = TRUE)
}
## query external ID to Term ID
gene <- names(geneList)
# Extract gene sets from GSON
gsid2gene <- gson@gsid2gene
# ID Match Check
if (!check_gene_id(gene, gsid2gene)) {
return(NULL)
}
# Prepare Gene Sets
geneSets <- split(gsid2gene$gene, gsid2gene$gsid)
gsea_res <- gsea(geneList = geneList,
gene_sets = geneSets,
weight = weight,
minGSSize = minGSSize,
maxGSSize = maxGSSize,
nPerm = nPerm,
exponent = exponent,
method = method,
adaptive = adaptive,
minPerm = minPerm,
maxPerm = maxPerm,
pvalThreshold = pvalThreshold,
seed = seed,
verbose = verbose,
...)
if (is.null(gsea_res) || nrow(gsea_res) == 0) {
return(NULL)
}
# Add Description
gsid2name <- gson@gsid2name
if (!is.null(gsid2name) && "ID" %in% names(gsea_res)) {
description <- gsid2name$name[match(gsea_res$ID, gsid2name$gsid)]
na_idx <- is.na(description)
description[na_idx] <- gsea_res$ID[na_idx]
gsea_res$Description <- description
} else {
if (!"Description" %in% names(gsea_res)) {
gsea_res$Description <- gsea_res$ID
}
}
# Calculate p.adjust
gsea_res$p.adjust <- p.adjust(gsea_res$pvalue, method=pAdjustMethod)
# Calculate qvalue
gsea_res$qvalue <- calculate_qvalue(gsea_res$pvalue)
# Filter by pvalueCutoff: both the raw p-value and the adjusted p-value
# must pass the cutoff, matching the historical DOSE/clusterProfiler
# behavior (see DOSE::GSEA_fgsea: res[res$pvalue <= pvalueCutoff, ] followed
# by res[res$p.adjust <= pvalueCutoff, ]).
#
# When reportNA = TRUE, rows with NA p-value (e.g. multilevel method under
# unbalanced gene-level statistics) are kept and automatically bypass the
# cutoff comparison, so pvalueCutoff = 1 together with reportNA = TRUE
# returns every gene set that passed size filtering. (YuLab-SMU/DOSE#88)
if (!is.null(pvalueCutoff)) {
gsea_res <- .gsea_drop_na_rows(gsea_res, reportNA)
pass_pval <- is.na(gsea_res$pvalue) | (gsea_res$pvalue <= pvalueCutoff)
pass_padj <- is.na(gsea_res$p.adjust) | (gsea_res$p.adjust <= pvalueCutoff)
gsea_res <- gsea_res[pass_pval & pass_padj, ]
}
if (nrow(gsea_res) == 0) {
return(NULL)
}
# Reorder columns
expected_cols <- c("ID", "Description", "setSize", "enrichmentScore", "NES", "pvalue", "p.adjust", "qvalue", "rank", "leading_edge", "core_enrichment")
# Ensure all expected columns exist to avoid error
missing_cols <- setdiff(expected_cols, names(gsea_res))
if (length(missing_cols) > 0) {
warning("Missing columns in GSEA result: ", paste(missing_cols, collapse=", "),
". Filling with NA. (Note: 'qvalue' may be missing if p-value distribution does not allow q-value calculation)")
for (col in missing_cols) {
gsea_res[[col]] <- NA
}
}
if ("qvalues" %in% names(gsea_res) && !"qvalue" %in% names(gsea_res)) {
gsea_res$qvalue <- gsea_res$qvalues
}
other_cols <- setdiff(names(gsea_res), expected_cols)
gsea_res <- gsea_res[, c(expected_cols, other_cols)]
# Set row names
# Ensure IDs are robust (handle NA and duplicates)
ids <- as.character(gsea_res$ID)
# Handle NA IDs (convert to string "NA")
if (any(is.na(ids))) {
warning("NA values detected in gene set IDs. Replacing with string 'NA'.")
ids[is.na(ids)] <- "NA"
}
# Handle Duplicate IDs
if (any(duplicated(ids))) {
dup_ids <- unique(ids[duplicated(ids)])
warning("Duplicate gene set IDs detected: ", paste(head(dup_ids), collapse=", "),
"... (Total ", length(dup_ids), "). Unique suffixes added.")
ids <- make.unique(ids)
}
rownames(gsea_res) <- ids
params <- list(pvalueCutoff = pvalueCutoff,
nPerm = nPerm,
pAdjustMethod = pAdjustMethod,
exponent = exponent,
minGSSize = minGSSize,
maxGSSize = maxGSSize,
reportNA = reportNA)
res <- new("gseaResult",
result = gsea_res,
organism = if (!is.null(gson@species)) gson@species else "UNKNOWN",
setType = if (!is.null(gson@gsname)) gsub(".*;", "", gson@gsname) else "UNKNOWN",
geneSets = geneSets,
geneList = geneList,
keytype = if (!is.null(gson@keytype)) gson@keytype else "UNKNOWN",
permScores = matrix(),
params = params,
gene2Symbol = character(),
readable = FALSE
)
return(res)
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.