Nothing
## These are informational notices, so they must go through `message()`.
## `yulab.utils::yulab_msg()` is the citation-banner builder -- it takes a
## package *name* and calls `packageDescription()` on it, so passing message
## text through it makes R warn "no package '<message>' was found".
check_gene_id <- function(gene, gsid2gene) {
if (!any(gene %in% gsid2gene$gene)) {
message("--> No gene can be mapped....")
sg <- utils::head(unique(gsid2gene$gene), 100)
sg <- sample(sg, min(length(sg), 6))
message("--> Expected input gene ID: ", paste0(sg, collapse=','))
message("--> return NULL...")
return(FALSE)
}
return(TRUE)
}
calculate_qvalue <- function(pvals) {
if (length(pvals) == 0)
return(numeric(0))
# Check if qvalue package is available
if (!requireNamespace("qvalue", quietly = TRUE)) {
warning("qvalue package not installed. qvalue column will be NA.")
return(rep(NA_real_, length(pvals)))
}
qv <- rep(NA_real_, length(pvals))
ok <- is.finite(pvals) & !is.na(pvals) & pvals >= 0 & pvals <= 1
if (any(!ok)) {
warning("Invalid p-values detected (NA, non-finite, <0, or >1). qvalue will be computed on valid p-values only.")
}
p <- pvals[ok]
if (length(p) == 0) {
return(qv)
}
if (all(p == 1)) {
qv[ok] <- 1
return(qv)
}
if (all(p == 0)) {
qv[ok] <- 0
return(qv)
}
qobj <- NULL
last_err <- NULL
try_qvalue <- function(expr) {
tryCatch(expr, error = function(e) {
last_err <<- e
NULL
})
}
qobj <- try_qvalue(qvalue::qvalue(p))
if (!inherits(qobj, "qvalue")) {
qobj <- try_qvalue(qvalue::qvalue(p, lambda = 0.05, pi0.method = "bootstrap"))
}
if (!inherits(qobj, "qvalue")) {
qobj <- try_qvalue(qvalue::qvalue(p, lambda = seq(0, 0.9, 0.05), pi0.method = "bootstrap"))
}
if (!inherits(qobj, "qvalue")) {
qobj <- try_qvalue(qvalue::qvalue(p, lambda = seq(0, 0.95, 0.05), pi0.method = "bootstrap"))
}
if (inherits(qobj, "qvalue")) {
qv[ok] <- qobj$qvalues
return(qv)
}
## A message, not a warning. q-value estimation legitimately fails when the
## p-values are all small and nearly equal (p * n / rank is then constant, so
## qvalue's spline fit has no variance to smooth). Nothing is wrong with the
## call: every gene set was still tested, p.adjust is still valid, and the
## result table itself shows the NA column. A warning says "look at this,
## something may be off"; a documented limitation of Storey's pi0 estimator is
## not that, and it fired once per result construction -- at eight call sites
## -- which in a test suite buries the diagnostics that do matter
## (measured 2026-10-27: one message per as_enrichResult(), none on print).
reason <- if (inherits(last_err, "error")) {
conditionMessage(last_err)
} else {
"the p-value distribution does not allow it (all p-values are close together)"
}
message("qvalue::qvalue() could not estimate q-values; the qvalue column is NA ",
"and p.adjust is unaffected. Reason: ", reason)
return(qv)
}
get_geneSet_index <- function(geneSets, minGSSize, maxGSSize) {
if (is.na(minGSSize) || is.null(minGSSize))
minGSSize <- 1
if (is.na(maxGSSize) || is.null(maxGSSize))
maxGSSize <- Inf
## index of geneSets in used.
## logical
geneSet_size <- sapply(geneSets, length)
idx <- minGSSize <= geneSet_size & geneSet_size <= maxGSSize
return(idx)
}
validate_gene_sets <- function(gene_sets) {
if (!is.list(gene_sets) || is.null(names(gene_sets))) {
stop("gene_sets must be a named list")
}
gene_sets <- lapply(gene_sets, function(x) {
if (!is.character(x)) {
stop("Each element in gene_sets must be a character vector")
}
unique(x)
})
return(gene_sets)
}
#' Compute leading-edge rank and meta for a single GSEA gene set.
#'
#' Re-runs the weighted running-enrichment-score accumulation used by
#' \code{\link{gseaScores}} on a single gene set to locate the peak
#' position and the core enrichment genes, matching the same semantics
#' as the internal GSEA loop. This helper is called from three places
#' that cannot rely on the main GSEA output having already been
#' prepared: \code{as_gseaResult()} (converter pipeline),
#' \code{.build_nsea_result()} (NSEA result builder), and the
#' multi-level result reconciler in \code{mnsea.R}.
#'
#' @param geneList named numeric vector of gene-level statistics,
#' assumed to be sorted in \strong{decreasing} order by the caller.
#' @param geneSet character vector of gene identifiers in the set of
#' interest.
#' @param exponent scalar weight exponent passed to
#' \code{gseaScores} (usually \code{1}).
#' @param scoreType one of \code{"std"}, \code{"pos"}, or \code{"neg"};
#' controls which tail of the running score curve defines the peak.
#'
#' @return A list with three elements:
#' \describe{
#' \item{rank}{Integer index into the sorted \code{geneList} of the
#' peak running score, or \code{0L} as a documented sentinel when
#' no usable weighted in-set signal exists (i.e. the gene set has
#' zero overlap with \code{names(geneList)}, the weighted sum
#' \code{N_R} of in-set gene weights is zero, or the running
#' score vector contains any non-finite value). \code{rank} is
#' always a finite integer; downstream code should not use
#' \code{NA_integer_} here because consumers commonly slice with
#' \code{seq_len(rank)} and compare with
#' \code{all(rank >= 0L)}.}
#' \item{leading_edge}{Human-readable \code{tags=X\%, list=Y\%,
#' signal=Z\%} summary string in the standard GSEA display
#' format. Empty-signal sentinel cases use
#' \code{"tags=0\%, list=0\%, signal=0\%"}; the string is a
#' display label only and should not be parsed by downstream
#' packages (use \code{core_enrichment} instead).}
#' \item{core_enrichment}{\code{"/"}-joined string of the gene
#' symbols contributing to the peak (the "leading edge subset").
#' Empty string (\code{""}) for the zero-signal sentinel cases.}
#' }
#'
#' @note Early-exit short-circuits are deliberately ordered so that any
#' bad input or zero-signal pathway returns the documented
#' \code{rank = 0L} sentinel \emph{before} any call to
#' \code{which.max() / which.min()} can fabricate a spurious peak.
#'
#' @seealso \code{\link{gseaScores}} for the full accumulation;
#' \code{\link{as_gseaResult}} for the main converter consumer.
#'
#' @keywords internal
gsea_leading_edge_details <- function(geneList, geneSet, exponent, scoreType) {
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")
}
genes <- names(geneList)
N <- length(geneList)
geneSet <- unique(intersect(as.character(geneSet), genes))
if (length(geneSet) == 0 || N == 0) {
return(list(rank = 0L, leading_edge = "tags=0%, list=0%, signal=0%", core_enrichment = ""))
}
in_set <- !is.na(match(genes, geneSet))
N_H <- sum(in_set)
if (N_H == 0) {
return(list(rank = 0L, leading_edge = "tags=0%, list=0%, signal=0%", core_enrichment = ""))
}
weights <- abs(geneList)
if (!isTRUE(all.equal(exponent, 1.0))) {
weights <- weights^exponent
}
N_R <- sum(weights[in_set], na.rm = TRUE)
N_miss <- N - N_H
if (N_R == 0) {
return(list(rank = 0L, leading_edge = "tags=0%, list=0%, signal=0%", core_enrichment = ""))
}
hit_inc <- (weights * in_set) / N_R
miss_inc <- if (N_miss == 0) rep(0, N) else (!in_set) / N_miss
running <- cumsum(hit_inc) - cumsum(miss_inc)
if (any(!is.finite(running))) {
return(list(rank = 0L, leading_edge = "tags=0%, list=0%, signal=0%", core_enrichment = ""))
}
if (scoreType == "pos") {
peak_idx <- which.max(running)
es <- running[peak_idx]
} else if (scoreType == "neg") {
peak_idx <- which.min(running)
es <- running[peak_idx]
} else {
max_es <- max(running)
min_es <- min(running)
stopifnot(is.finite(max_es), is.finite(min_es))
if (isTRUE(abs(max_es) >= abs(min_es))) {
peak_idx <- which.max(running)
es <- max_es
} else {
peak_idx <- which.min(running)
es <- min_es
}
}
if (is.na(peak_idx) || length(peak_idx) == 0) {
return(list(rank = 0L, leading_edge = "tags=0%, list=0%, signal=0%", core_enrichment = ""))
}
peak_idx <- peak_idx[[1]]
if (es >= 0) {
rank <- as.integer(peak_idx)
ledge_range <- seq_len(peak_idx)
list_frac <- peak_idx / N
} else {
rank <- as.integer(N - peak_idx + 1)
ledge_range <- peak_idx:N
list_frac <- (N - peak_idx + 1) / N
}
core_genes <- genes[ledge_range][in_set[ledge_range]]
hits_in_ledge <- length(core_genes)
tags_frac <- hits_in_ledge / N_H
signal_frac <- tags_frac * (1 - list_frac) * (N / max(N_miss, 1))
leading_edge <- paste0(
"tags=", round(tags_frac * 100), "%",
", list=", round(list_frac * 100), "%",
", signal=", round(signal_frac * 100), "%"
)
list(
rank = rank,
leading_edge = leading_edge,
core_enrichment = paste0(core_genes, collapse = "/")
)
}
#' Common parameters for enrichit functions
#'
#' @param geneList A named numeric vector of gene statistics (e.g., log fold change), ranked in descending order.
#' @param gene_sets A named list of gene sets. Each element is a character vector of genes.
#' @param nPerm Number of permutations for p-value calculation (default: 1000).
#' @param exponent Weighting exponent for enrichment score (default: 1.0).
#' @param minGSSize minimal size of each geneSet for analyzing
#' @param maxGSSize maximal size of each geneSet for analyzing
#' @param pvalueCutoff P-value cutoff.
#' @param pAdjustMethod P-value adjustment method (e.g., "BH").
#' @param verbose Logical. Print progress messages.
#' @param gson A GSON object containing gene set information.
#' @param method Permutation method.
#' @param adaptive Logical. Use adaptive permutation.
#' @param minPerm Minimum permutations for adaptive mode.
#' @param maxPerm Maximum permutations for adaptive mode.
#' @param pvalThreshold P-value threshold for early stopping.
#' @keywords internal
#' @name enrichit_params
NULL
get_enriched <- function(object) {
Over <- object@result
## Subsetting with a logical that carries NA keeps the row but blanks every
## column (`d[c(NA, TRUE), ]` returns one all-NA row and one real row), so a
## term whose pvalue or p.adjust is NA came back as a corrupted row with
## ID = NA. `which()` drops the NA positions and leaves a clean row index.
keep_rows <- function(df, cond) {
if (length(cond) == 0L) {
return(df)
}
df[which(cond), , drop = FALSE]
}
pvalueCutoff <- object@pvalueCutoff
if (length(pvalueCutoff) != 0) {
Over <- keep_rows(Over, Over$pvalue <= pvalueCutoff)
Over <- keep_rows(Over, Over$p.adjust <= pvalueCutoff)
}
qvalueCutoff <- object@qvalueCutoff
## `nrow(Over) > 0L` is load-bearing: on an empty frame the two all-NA
## checks below are vacuously TRUE, so without it a result whose terms were
## all filtered out by pvalueCutoff would print "qvalue could not be
## estimated for any term" -- a warning about a column that was never the
## reason there is nothing to show. show(), dim(), head(), tail() and
## as.data.frame() all route through here, so that would fire on every
## inspect of a no-hit result.
if (length(qvalueCutoff) != 0 && nrow(Over) > 0L) {
qv <- Over$qvalue
## Row-wise q-value filter. Rows whose own qvalue is NA bypass this
## cutoff and keep the fate pvalueCutoff already gave them: dropping
## them would hide terms the user asked to see, and the old
## "one NA anywhere disables the cutoff for every term" behaviour made
## a single unestimable qvalue leak unfiltered rows into the result
## with no message (clusterProfiler#710, #584, #614, #332).
if (is.null(qv)) {
warning(
"the result has no `qvalue` column; qvalueCutoff = ",
qvalueCutoff, " was not applied. Filter on p.adjust instead."
)
} else if (all(is.na(qv))) {
warning(
"qvalue could not be estimated for any term; qvalueCutoff = ",
qvalueCutoff, " was not applied. Filter on p.adjust instead."
)
} else {
if (any(is.na(qv))) {
warning(
"qvalue is NA for ", sum(is.na(qv)), " of ", nrow(Over),
" terms; those rows bypass qvalueCutoff (their pvalue/p.adjust",
" filters still apply). Use pvalueCutoff to filter them."
)
}
Over <- keep_rows(Over, is.na(qv) | qv <= qvalueCutoff)
}
}
object@result <- Over
return(object)
}
TERM2NAME <- function(term, gson) {
if (inherits(gson, "environment")) {
PATHID2NAME <- get("PATHID2NAME", envir = gson)
#if (is.null(PATHID2NAME) || is.na(PATHID2NAME)) {
if (is.null(PATHID2NAME) || all(is.na(PATHID2NAME))) {
return(as.character(term))
}
res <- PATHID2NAME[term]
i <- is.na(res)
res[i] <- term[i]
} else if (inherits(gson, "GSON")) {
gsid2name <- gson@gsid2name
res <- as.character(term)
if (!is.null(gsid2name) && nrow(gsid2name) > 0L) {
i <- match(as.character(term), as.character(gsid2name$gsid))
j <- !is.na(i)
res[j] <- as.character(gsid2name$name[i[j]])
}
} else {
res <- as.character(term)
}
names(res) <- term
return(res)
}
TERMID2EXTID <- function(term, gson) {
if (inherits(gson, "GSON")) {
gsid2gene <- gson@gsid2gene
res <- split(
as.character(gsid2gene$gene),
as.character(gsid2gene$gsid)
)
res <- res[as.character(term)]
names(res) <- as.character(term)
i <- vapply(res, is.null, logical(1))
res[i] <- list(character(0))
return(res)
} else if (inherits(gson, "environment")) {
PATHID2EXTID <- get("PATHID2EXTID", envir = gson)
res <- PATHID2EXTID[term]
return(res)
} else {
stop("gson not supported")
}
}
# Filter every gene set to a shared universe in one pass.
#
# `lapply(gene_sets, intersect, universe)` is correct but hashes the whole
# universe once per set: 14,209 human GO BP sets (avg 80 ids) against an 18,842
# gene universe cost 14.0 s, measured 2026-10-18, and this pattern is used by
# ORA (restricted universe), GSEA, NSEA, DSEA and Bayes enrichment. Mapping the
# concatenated ids once and splitting back by the original set lengths costs
# 0.9 s and is byte-identical, including set names, element order and empty
# sets (pinned by a test).
filter_gene_sets <- function(gene_sets, universe) {
if (!length(gene_sets)) {
return(list())
}
ids <- unlist(gene_sets, use.names = FALSE)
groups <- rep.int(seq_along(gene_sets), lengths(gene_sets))
keep <- !is.na(ids) & !is.na(match(ids, universe))
parts <- split(ids[keep], factor(groups[keep], levels = seq_along(gene_sets)),
drop = FALSE)
out <- lapply(parts, unique)
names(out) <- names(gene_sets)
out
}
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.