% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/enrichPathway.R
\name{enrichPathway}
\alias{enrichPathway}
\title{Pathway Enrichment Analysis on KEGG-Based Node Sets}
\usage{
enrichPathway(
  test_set,
  background_set,
  pathway_set,
  entity = c("ko", "compound", "integrated"),
  pvalueCutoff = 0.05,
  add_hits = FALSE
)
}
\arguments{
\item{test_set}{Character vector of node identifiers, such as KEGG compound
or KO identifiers. A matrix or data frame may also be supplied, in which
case unique nodes from the first two columns are used.}

\item{background_set}{Character vector of node identifiers defining the
background universe. A network matrix or data frame may also be supplied.}

\item{pathway_set}{Either a character vector of KEGG reference pathway
identifiers or a named list in which each element contains the node
members of one pathway.}

\item{entity}{Character string specifying the entity type to analyse:
\code{"ko"} for KOs, \code{"compound"} for compounds, or
\code{"integrated"} for both. Default \code{"ko"}.}

\item{pvalueCutoff}{Numeric significance threshold applied to adjusted
p-values after Benjamini–Hochberg correction. Default \code{0.05}.}

\item{add_hits}{Logical. If \code{TRUE}, adds a \code{Test_Hits} column
containing the test nodes found in each pathway. Default \code{FALSE}.}
}
\value{
A data frame containing pathway enrichment results with columns:
\describe{
\item{Pathway_ID}{KEGG pathway identifier, such as
\code{"map00380"}.}
\item{Description}{Pathway description retrieved from KEGG.}
\item{bg_overlap}{Number of background nodes belonging to the pathway.}
\item{test_overlap}{Number of test nodes belonging to the pathway.}
\item{Test_Hits}{Optional semicolon-separated test nodes belonging to the
pathway. Included only when \code{add_hits = TRUE}.}
\item{p_value}{Raw hypergeometric p-value.}
\item{p_adj}{Adjusted p-value obtained using the Benjamini–Hochberg
method.}
\item{Enrichment_Ratio}{Ratio between the test-set pathway proportion and
the background pathway proportion.}
\item{significance}{\code{"significant"} or \code{"NS"}, determined using
\code{pvalueCutoff}.}
}

The returned data frame can be visualised using
\code{\link{enrichmentDotPlot}}.
}
\description{
Performs pathway over-representation analysis using the hypergeometric test
with Benjamini–Hochberg correction on nodes from KEGG-derived networks.
Supports KO-level, compound-level, and integrated KO–compound analyses.
}
\details{
If \code{test_set} or \code{background_set} is supplied as a matrix or data
frame, unique nodes are extracted from the first two columns.

Before enrichment analysis, the test set is restricted to nodes present in
the background set. Enrichment is then calculated using the hypergeometric
distribution with \code{\link[stats]{phyper}}, followed by
Benjamini–Hochberg adjustment using \code{\link[stats]{p.adjust}}.

Pathways with no test-set overlap are excluded from the returned results.
}
\note{
Very small test sets, or test sets that are nearly identical to the
background set, may produce uninformative enrichment results.
}
\examples{
## Load the precomputed example network
## See buildKeggNetwork() for its construction
data(MetaPathNet_example_network)

## Define a small test set from the example network
test_nodes <- c(
  "K00463",
  "K00453",
  "cpd:C00078",
  "cpd:C02700"
)

## Run integrated pathway over-representation analysis
enrich_res <- enrichPathway(
  test_set = test_nodes,
  background_set = MetaPathNet_example_network,
  pathway_set = c("map00380", "map00400"),
  entity = "integrated",
  pvalueCutoff = 1,
  add_hits = TRUE
)

## Preview the enrichment results
head(enrich_res)

## Visualise the enrichment results
if (nrow(enrich_res) > 0) {
  enrichmentDotPlot(enrich_res)
}

}
\seealso{
\code{\link{enrichmentDotPlot}},
\code{\link{getPathIDs}}
}
