% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stats_tests.R
\name{run.gsea}
\alias{run.gsea}
\title{Run Gene Set Enrichment Analysis}
\usage{
run.gsea(de.results, genes, pathways, min.size = 15, max.size = 500)
}
\arguments{
\item{de.results}{Data frame as returned by \code{run.limma.de()}.
Must contain a \code{logFC} column. Row names are probe IDs.}

\item{genes}{Data frame of gene annotations as returned by
\code{extract.expression()$gene}. Must contain columns \code{"ID"} for
probe identifiers and \code{"Gene symbol"} for gene symbols matching
the format used by pathway databases such as MSigDB.}

\item{pathways}{Named list of character vectors, where each element is a
gene set and names are pathway labels. MSigDB or GO gene sets in this
format can be loaded via \code{msigdbr}.}

\item{min.size}{Integer. Minimum number of genes required in a gene set
for it to be tested. Default is \code{15}.}

\item{max.size}{Integer. Maximum gene set size. Default is \code{500}.}
}
\value{
A data frame with one row per tested pathway, containing:
\describe{
\item{pathway}{Gene set name.}
\item{pval}{Nominal p-value.}
\item{padj}{BH-adjusted p-value across all tested pathways.}
\item{NES}{Normalized enrichment score. Positive values indicate
enrichment among upregulated genes; negative values indicate
enrichment among downregulated genes.}
\item{size}{Number of genes from the pathway present in the ranked list.}
\item{leadingEdge}{List-column of genes driving the enrichment score.}
}
}
\description{
Tests whether predefined gene sets (e.g., pathways or GO terms) are
systematically enriched among genes ranked by differential expression,
using the fgseaMultilevel algorithm from \code{fgsea}.
}
\details{
Uses the \code{fgseaMultilevel} algorithm, which estimates p-values using
an adaptive multilevel splitting Monte Carlo approach. This is more
accurate than the original permutation-based \code{fgseaSimple} and does
not require a fixed permutation count.

GSEA operates on the full ranked gene list from \code{run.limma.de()}
rather than a filtered subset, preserving information from all genes. Probe
IDs from the TopTable row names are resolved to gene symbols via the
\code{genes} annotation data frame before matching against pathway gene
sets. Probes with no gene annotation are silently dropped from the ranked
list, as they cannot be matched to any pathway. The \code{leadingEdge}
genes are strong candidates for follow-up with \code{analyze.gene()} or
\code{gene.analysis.plot()}.
}
\examples{
\donttest{
library(msigdbr)
geo <- extract.expression(load.geo.soft(accession = "GDS507",
                                                 log.transform = TRUE))
hallmark.df <- msigdbr(species = "Homo sapiens", category = "H")
pathways <- split(hallmark.df$gene_symbol, hallmark.df$gs_name)
de.results <- run.limma.de(geo)
gsea.results <- run.gsea(de.results, geo$gene, pathways)
head(gsea.results[order(gsea.results$padj), ])
}

}
