R/utilities.R

Defines functions filter_gene_sets TERMID2EXTID TERM2NAME get_enriched gsea_leading_edge_details validate_gene_sets get_geneSet_index calculate_qvalue check_gene_id

Documented in gsea_leading_edge_details

## 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
}

Try the enrichit package in your browser

Any scripts or data that you put into this service are public.

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