KEGG Pathway Enrichment Analysis Guide
Overview
KEGG (Kyoto Encyclopedia of Genes and Genomes) pathway enrichment analysis identifies biological pathways that are statistically over-represented among differentially expressed genes. This guide covers the two main enrichment approaches (ORA and GSEA), critical workflow decisions such as splitting genes by directionality, tool selection between R clusterProfiler and Python gseapy, and strategies for handling the notoriously unreliable KEGG REST API. It addresses recurring failure modes that produce incorrect pathway counts or stalled analyses.
The three most common errors in KEGG pathway analysis are: (1) combining up-regulated and down-regulated genes into a single enrichment run, which masks true pathway signals; (2) analysis failures caused by KEGG REST API timeouts with no fallback strategy; and (3) delaying result reporting while attempting cosmetic pathway name lookups that may never complete. This guide provides concrete solutions for each.
Key Concepts
ORA vs GSEA
Over-Representation Analysis (ORA) and Gene Set Enrichment Analysis (GSEA) are the two primary methods for pathway enrichment, and they differ in both input and statistical approach.
ORA takes a pre-filtered gene list (e.g., genes with padj < 0.05 and |log2FC| > 1.5) and tests whether KEGG pathway members are over-represented in that list relative to a background universe. ORA uses a hypergeometric test (Fisher's exact test). It is straightforward but discards magnitude information and depends heavily on the significance cutoff chosen.
GSEA takes a ranked list of all genes (typically ranked by log2 fold change or a signed significance statistic) without any cutoff. It computes a running enrichment score by walking down the ranked list and identifies pathways whose members cluster toward the top or bottom of the ranking. GSEA captures subtle coordinated changes that ORA may miss.
In practice, ORA via enrichKEGG() (clusterProfiler) or gp.enrichr() (gseapy) is the more common starting point. GSEA via gseKEGG() or gp.prerank() is preferred when you want to avoid arbitrary cutoffs or when effect sizes are small.
Directionality in Enrichment
When performing ORA, gene directionality -- whether a gene is up-regulated or down-regulated -- is critical. A single pathway can contain genes regulated in opposite directions. If up-regulated and down-regulated genes are combined into one list, their opposing signals cancel out, diluting the enrichment signal and masking genuinely enriched pathways. Running enrichment separately for up-regulated and down-regulated gene sets produces more accurate and interpretable results. This splitting is mandatory for ORA. GSEA inherently handles directionality through the signed ranking, though interpreting leading-edge genes by direction is still important.
KEGG Organism Codes
KEGG uses three-letter (or four-letter) organism codes to identify species-specific pathway databases. Using the wrong code silently returns empty results. Common codes:
| Organism |
Code |
| Human |
hsa |
| Mouse |
mmu |
| Rat |
rno |
| Zebrafish |
dre |
| Drosophila |
dme |
| C. elegans |
cel |
| E. coli K-12 |
eco |
| P. aeruginosa PA14 |
pau |
| P. aeruginosa PAO1 |
pae |
| S. cerevisiae |
sce |
| A. thaliana |
ath |
Gene ID format also varies by organism: eukaryotic species typically require Entrez gene IDs, while bacterial species use locus tags. Mismatched ID types are a silent failure mode.
KEGG API Reliability
The KEGG REST API (rest.kegg.jp) is rate-limited, frequently slow, and prone to timeouts. Both clusterProfiler::enrichKEGG() and direct HTTP requests to KEGG can fail unpredictably. Planning for API failures is not optional -- it is a necessary part of any KEGG-based workflow. Strategies include pre-fetching and caching pathway data, using offline gene set databases bundled with gseapy, and implementing retry logic with timeouts.
Pre-flight Interview
Settle these with the user before writing any analysis code.
decisions:
- id: D1
param: organismCode
kind: required
source: upstream
ask: "Which species should pathways be looked up for?"
default: "carried from the dataset"
- id: D2
param: identifierMapping
kind: required
source: data
depends_on: [D1]
ask: "Which identifier type do the genes carry, and how should unmapped ones be handled?"
default: null
- id: D3
param: testingApproach
kind: required
source: upstream
ask: "Test a significant-gene list against pathways (over-representation), or the whole ranked list without a cut (enrichment)?"
default: "over-representation when the input is a gene list"
- id: D4
param: backgroundSet
kind: required
source: upstream
depends_on: [D3]
ask: "Which genes form the background - everything measured in this experiment, or the whole annotated genome?"
default: "the genes tested in this experiment"
skip_if: "ranked-list enrichment, which uses the ranking rather than a background"
- id: D5
param: pathwayScope
kind: optional
source: user
ask: "Should all pathway categories be tested, or only metabolism, signalling, or disease maps?"
default: "all categories"
- id: D6
param: significanceThreshold
kind: required
source: user
ask: "How strong must a pathway's evidence be, after correcting for the number of pathways tested?"
default: "adjusted p-value 0.05"
D4 is the decision most often skipped and the one that most changes the answer.
Using the whole genome as background when the experiment only measured
expressed genes makes every tissue-specific pathway look enriched - the
enrichment is against genes that were never measurable, not against the
experiment.
Decision Framework
Question: What enrichment analysis do you need?
|
+-- Have a pre-filtered DEG list (with cutoffs applied)?
| +-- Yes --> ORA
| | +-- Using R? --> clusterProfiler::enrichKEGG()
| | +-- Using Python? --> gseapy.enrichr()
| | +-- KEGG API failing? --> gseapy with offline gene sets
| +-- No, want cutoff-free analysis --> GSEA
| +-- Using R? --> clusterProfiler::gseKEGG()
| +-- Using Python? --> gseapy.prerank()
|
+-- Need to split by direction?
| +-- ORA --> YES, always split up/down (mandatory)
| +-- GSEA --> No split needed (direction encoded in ranking)
|
+-- KEGG API unreliable?
+-- Try cached/pre-fetched data first
+-- Fall back to gseapy offline databases
+-- Use retry logic with short timeouts
| Scenario |
Recommended Approach |
Rationale |
| Standard ORA with R |
clusterProfiler::enrichKEGG(), split by direction |
Most widely used, integrates with Bioconductor ecosystem |
| Standard ORA with Python |
gseapy.enrichr() with KEGG_2021_Human |
Offline gene sets avoid API dependency |
| Cutoff-free enrichment |
GSEA via gseKEGG() or gp.prerank() |
Captures subtle coordinated changes, no arbitrary threshold |
| KEGG API is down |
Switch to gseapy offline databases |
gseapy bundles KEGG gene sets locally |
| Comparing conditions |
Run separate up/down enrichment per condition |
Enables direction-aware set operations across conditions |
| Non-model organism |
Verify organism code, use KEGGREST to check availability |
Wrong code silently returns empty results |
Best Practices
Always split ORA by gene direction. Run enrichKEGG() or gp.enrichr() separately for up-regulated and down-regulated genes. Combining them inflates the gene list, dilutes enrichment signal, and produces incorrect pathway counts. Report the union of significant pathways from both directions.
Specify the background universe explicitly. Set the universe to all tested genes (the full set from your differential expression analysis), not just the significant ones. Omitting the universe defaults to all genes in the KEGG database, which inflates significance for well-studied pathways.
Pre-fetch and cache KEGG data before running enrichment. Download pathway-gene mappings at the start of the analysis and save them locally. This avoids mid-analysis failures when the KEGG API becomes unresponsive and makes the analysis reproducible.
Report the numeric answer before resolving pathway names. Once you have computed the count or list of significant pathway IDs, emit that result immediately. Resolving IDs to human-readable names via additional KEGG API calls is cosmetic and can timeout, losing the primary result.
Apply multiple testing correction consistently. Use adjusted p-values (p.adjust < 0.05, typically BH method) rather than raw p-values. Both clusterProfiler and gseapy apply correction by default, but always verify the cutoff is on the adjusted value.
Verify gene ID format matches the organism. Eukaryotic KEGG pathways expect Entrez gene IDs; bacterial species expect locus tags. A mismatch silently returns zero enriched pathways. Use bitr() in clusterProfiler or equivalent ID conversion if your input uses gene symbols.
Use gseapy as a fallback when clusterProfiler fails. When enrichKEGG() fails due to KEGG API issues, gseapy's enrichr() function with bundled offline gene sets (e.g., KEGG_2021_Human) provides equivalent ORA results without any network dependency.
Common Pitfalls
Combining up-regulated and down-regulated genes into a single enrichment run. Pathways with genes regulated in opposite directions cancel out, producing fewer significant pathways than the true count. Results from combined lists are unreliable. Example of the anti-pattern:
# WRONG: combining up and down genes into one list
all_sig_genes <- rownames(subset(res, padj < 0.05 & abs(log2FoldChange) > 1.5))
ekegg <- enrichKEGG(gene = all_sig_genes, ...) # Will miss pathways
- How to avoid: Always split DEGs by direction before ORA. Run enrichment twice (once for up, once for down) and take the union of significant pathways.
Using the wrong KEGG organism code. KEGG silently returns empty results for invalid or mismatched organism codes. This is especially common for bacterial species with multiple strain-specific codes (e.g., pae for PAO1 vs pau for PA14).
- How to avoid: Confirm the organism code from the KEGG organism list before running enrichment. For bacteria, verify the specific strain code.
Gene ID type mismatch. Providing gene symbols when KEGG expects Entrez IDs (or locus tags for bacteria) silently yields zero enriched pathways with no error message.
- How to avoid: Check the expected ID type for your organism. Use
clusterProfiler::bitr() or equivalent to convert gene symbols to Entrez IDs before enrichment.
Not handling KEGG API timeouts. The KEGG REST API frequently times out, causing enrichKEGG() to fail mid-analysis. Without error handling, the entire analysis is lost.
- How to avoid: Wrap KEGG API calls in retry logic with short timeouts (30 seconds). Pre-fetch pathway data at the start. Have gseapy as a fallback.
Delaying the answer to resolve pathway names. Calling keggGet() to convert pathway IDs to human-readable names after computing results can timeout, losing the numeric answer entirely. Example of the anti-pattern:
# BAD: answer delayed by name lookup that may hang
result_ids <- setdiff(pathways_condA, pathways_condB)
names <- keggGet(result_ids) # Can timeout -- answer never emitted
count <- length(result_ids)
- How to avoid: Report pathway IDs and counts immediately. Resolve names only after the primary result is secured, inside a
tryCatch() or try/except block.
Omitting the background universe. Not specifying the universe parameter defaults to the entire KEGG gene database for that organism, inflating statistical significance for pathways containing well-annotated housekeeping genes.
- How to avoid: Always pass
universe = rownames(res) (all tested genes from the DE analysis) to enrichKEGG().
Using raw p-values instead of adjusted p-values for filtering. Reporting pathways with p < 0.05 without multiple testing correction dramatically increases false positives.
- How to avoid: Always filter on
p.adjust < 0.05. Verify that the column you are filtering is the adjusted value, not the raw p-value.
Workflow
Step 1: Prepare gene lists
- Filter significant DEGs from differential expression results (e.g., padj < 0.05, |log2FC| > 1.5)
- Split into up-regulated and down-regulated gene sets
- Convert gene IDs to the format expected by KEGG (Entrez IDs or locus tags)
library(clusterProfiler)
# Filter significant DEGs
sig_genes <- subset(res, padj < 0.05 & abs(log2FoldChange) > 1.5)
# MANDATORY: Split by direction BEFORE running enrichment
up_genes <- rownames(subset(sig_genes, log2FoldChange > 0))
dn_genes <- rownames(subset(sig_genes, log2FoldChange < 0))
cat("Up-regulated genes:", length(up_genes), "\n")
cat("Down-regulated genes:", length(dn_genes), "\n")
Step 2: Pre-fetch KEGG data (recommended)
- Cache pathway-gene mappings locally before running enrichment
- Decision point: If KEGG API is accessible, proceed with live queries. If not, switch to offline gene sets (Step 2b).
R (KEGGREST package):
library(KEGGREST)
pathway_list <- tryCatch(
keggList("pathway", organism_code),
error = function(e) NULL
)
Python (requests with caching):
import requests
import json
import os
cache_file = f"kegg_{organism_code}_pathways.json"
if os.path.exists(cache_file):
with open(cache_file) as f:
pathway_map = json.load(f)
else:
resp = requests.get(
f"https://rest.kegg.jp/list/pathway/{organism_code}", timeout=30
)
if resp.ok:
pathway_map = dict(
line.split("\t") for line in resp.text.strip().split("\n")
)
with open(cache_file, 'w') as f:
json.dump(pathway_map, f)
Step 3: Run enrichment separately for each direction
- Run ORA twice: once for up-regulated genes, once for down-regulated genes
- Always specify the universe (all tested genes)
R (clusterProfiler):
ekegg_up <- enrichKEGG(gene = up_genes, organism = organism_code,
universe = rownames(res), pvalueCutoff = 0.05)
ekegg_dn <- enrichKEGG(gene = dn_genes, organism = organism_code,
universe = rownames(res), pvalueCutoff = 0.05)
up_pathways <- subset(as.data.frame(ekegg_up), p.adjust < 0.05)$ID
dn_pathways <- subset(as.data.frame(ekegg_dn), p.adjust < 0.05)$ID
all_sig_pathways <- union(up_pathways, dn_pathways)
cat("Significant pathways (up):", length(up_pathways), "\n")
cat("Significant pathways (down):", length(dn_pathways), "\n")
cat("Total unique significant pathways:", length(all_sig_pathways), "\n")
Python (gseapy):
import gseapy as gp
up_genes = sig_genes[sig_genes['log2FoldChange'] > 0].index.tolist()
dn_genes = sig_genes[sig_genes['log2FoldChange'] < 0].index.tolist()
enr_up = gp.enrichr(gene_list=up_genes, gene_sets='KEGG_2021_Human',
organism='human', outdir=None)
enr_dn = gp.enrichr(gene_list=dn_genes, gene_sets='KEGG_2021_Human',
organism='human', outdir=None)
Step 4: Report results immediately
- Emit pathway IDs and counts before attempting name resolution
- Optionally resolve pathway names in a non-blocking manner
result_ids <- setdiff(pathways_condA, pathways_condB)
count <- length(result_ids)
cat("Answer:", count, "pathways unique to condition A\n")
cat("Pathway IDs:", paste(result_ids, collapse = ", "), "\n")
# Optional: resolve names (non-blocking)
names <- tryCatch(keggGet(result_ids), error = function(e) NULL)
Step 5: Cross-condition comparison (if applicable)
- Run separate up/down enrichment for each condition (4 enrichKEGG calls total)
- Compare pathway sets within the same direction
- Report the union of direction-specific unique pathways
# Condition A
up_pathways_A <- subset(as.data.frame(ekegg_up_A), p.adjust < 0.05)$ID
dn_pathways_A <- subset(as.data.frame(ekegg_dn_A), p.adjust < 0.05)$ID
# Condition B
up_pathways_B <- subset(as.data.frame(ekegg_up_B), p.adjust < 0.05)$ID
dn_pathways_B <- subset(as.data.frame(ekegg_dn_B), p.adjust < 0.05)$ID
# Find pathways unique to condition A in each direction
unique_up <- setdiff(up_pathways_A, up_pathways_B)
unique_dn <- setdiff(dn_pathways_A, dn_pathways_B)
# Union
unique_to_A <- union(unique_up, unique_dn)
cat("Pathways in A but not B:", length(unique_to_A), "\n")
cat(" From up-regulated:", length(unique_up), "-",
paste(unique_up, collapse = ", "), "\n")
cat(" From down-regulated:", length(unique_dn), "-",
paste(unique_dn, collapse = ", "), "\n")
Step 6: Handle API failures with retry logic
- If KEGG API calls fail, retry with timeout before falling back to offline data
fetch_kegg_with_retry <- function(organism_code, max_retries = 3,
timeout_sec = 30) {
for (i in seq_len(max_retries)) {
result <- tryCatch({
R.utils::withTimeout(
keggList("pathway", organism_code),
timeout = timeout_sec
)
}, error = function(e) NULL)
if (!is.null(result)) return(result)
Sys.sleep(2)
}
warning("KEGG API unreachable after retries. Proceeding without pathway names.")
return(NULL)
}
Further Reading
Related Skills
gseapy-gene-enrichment -- Python-based gene set enrichment analysis; use as a fallback when clusterProfiler KEGG API calls fail, or as the primary tool for Python-based workflows
deseq2-differential-expression / pydeseq2-differential-expression -- Upstream differential expression analysis that produces the DEG lists used as input to KEGG pathway enrichment
1---2name: kegg-pathway-analysis3description: "Guide to KEGG pathway enrichment for DEG results. Covers ORA vs GSEA, mandatory directionality splitting, KEGG organism codes, API failure handling with offline fallbacks, cross-condition comparisons, and answer-first reporting. Consult when running enrichment with clusterProfiler or gseapy."4license: CC-BY-4.05metadata:6 source: https://skillmd.com/skills/jaechang-hits/kegg-pathway-analysis7---89# KEGG Pathway Enrichment Analysis Guide1011## Overview1213KEGG (Kyoto Encyclopedia of Genes and Genomes) pathway enrichment analysis identifies biological pathways that are statistically over-represented among differentially expressed genes. This guide covers the two main enrichment approaches (ORA and GSEA), critical workflow decisions such as splitting genes by directionality, tool selection between R clusterProfiler and Python gseapy, and strategies for handling the notoriously unreliable KEGG REST API. It addresses recurring failure modes that produce incorrect pathway counts or stalled analyses.1415The three most common errors in KEGG pathway analysis are: (1) combining up-regulated and down-regulated genes into a single enrichment run, which masks true pathway signals; (2) analysis failures caused by KEGG REST API timeouts with no fallback strategy; and (3) delaying result reporting while attempting cosmetic pathway name lookups that may never complete. This guide provides concrete solutions for each.1617## Key Concepts1819### ORA vs GSEA2021Over-Representation Analysis (ORA) and Gene Set Enrichment Analysis (GSEA) are the two primary methods for pathway enrichment, and they differ in both input and statistical approach.2223**ORA** takes a pre-filtered gene list (e.g., genes with padj < 0.05 and |log2FC| > 1.5) and tests whether KEGG pathway members are over-represented in that list relative to a background universe. ORA uses a hypergeometric test (Fisher's exact test). It is straightforward but discards magnitude information and depends heavily on the significance cutoff chosen.2425**GSEA** takes a ranked list of all genes (typically ranked by log2 fold change or a signed significance statistic) without any cutoff. It computes a running enrichment score by walking down the ranked list and identifies pathways whose members cluster toward the top or bottom of the ranking. GSEA captures subtle coordinated changes that ORA may miss.2627In practice, ORA via `enrichKEGG()` (clusterProfiler) or `gp.enrichr()` (gseapy) is the more common starting point. GSEA via `gseKEGG()` or `gp.prerank()` is preferred when you want to avoid arbitrary cutoffs or when effect sizes are small.2829### Directionality in Enrichment3031When performing ORA, gene directionality -- whether a gene is up-regulated or down-regulated -- is critical. A single pathway can contain genes regulated in opposite directions. If up-regulated and down-regulated genes are combined into one list, their opposing signals cancel out, diluting the enrichment signal and masking genuinely enriched pathways. Running enrichment separately for up-regulated and down-regulated gene sets produces more accurate and interpretable results. This splitting is mandatory for ORA. GSEA inherently handles directionality through the signed ranking, though interpreting leading-edge genes by direction is still important.3233### KEGG Organism Codes3435KEGG uses three-letter (or four-letter) organism codes to identify species-specific pathway databases. Using the wrong code silently returns empty results. Common codes:3637| Organism | Code |38|---|---|39| Human | hsa |40| Mouse | mmu |41| Rat | rno |42| Zebrafish | dre |43| Drosophila | dme |44| C. elegans | cel |45| E. coli K-12 | eco |46| P. aeruginosa PA14 | pau |47| P. aeruginosa PAO1 | pae |48| S. cerevisiae | sce |49| A. thaliana | ath |5051Gene ID format also varies by organism: eukaryotic species typically require Entrez gene IDs, while bacterial species use locus tags. Mismatched ID types are a silent failure mode.5253### KEGG API Reliability5455The KEGG REST API (`rest.kegg.jp`) is rate-limited, frequently slow, and prone to timeouts. Both `clusterProfiler::enrichKEGG()` and direct HTTP requests to KEGG can fail unpredictably. Planning for API failures is not optional -- it is a necessary part of any KEGG-based workflow. Strategies include pre-fetching and caching pathway data, using offline gene set databases bundled with gseapy, and implementing retry logic with timeouts.5657## Pre-flight Interview5859Settle these with the user before writing any analysis code.6061```yaml62decisions:63 - id: D164 param: organismCode65 kind: required66 source: upstream67 ask: "Which species should pathways be looked up for?"68 default: "carried from the dataset"6970 - id: D271 param: identifierMapping72 kind: required73 source: data74 depends_on: [D1]75 ask: "Which identifier type do the genes carry, and how should unmapped ones be handled?"76 default: null7778 - id: D379 param: testingApproach80 kind: required81 source: upstream82 ask: "Test a significant-gene list against pathways (over-representation), or the whole ranked list without a cut (enrichment)?"83 default: "over-representation when the input is a gene list"8485 - id: D486 param: backgroundSet87 kind: required88 source: upstream89 depends_on: [D3]90 ask: "Which genes form the background - everything measured in this experiment, or the whole annotated genome?"91 default: "the genes tested in this experiment"92 skip_if: "ranked-list enrichment, which uses the ranking rather than a background"9394 - id: D595 param: pathwayScope96 kind: optional97 source: user98 ask: "Should all pathway categories be tested, or only metabolism, signalling, or disease maps?"99 default: "all categories"100101 - id: D6102 param: significanceThreshold103 kind: required104 source: user105 ask: "How strong must a pathway's evidence be, after correcting for the number of pathways tested?"106 default: "adjusted p-value 0.05"107```108109D4 is the decision most often skipped and the one that most changes the answer.110Using the whole genome as background when the experiment only measured111expressed genes makes every tissue-specific pathway look enriched - the112enrichment is against genes that were never measurable, not against the113experiment.114115## Decision Framework116117```118Question: What enrichment analysis do you need?119|120+-- Have a pre-filtered DEG list (with cutoffs applied)?121| +-- Yes --> ORA122| | +-- Using R? --> clusterProfiler::enrichKEGG()123| | +-- Using Python? --> gseapy.enrichr()124| | +-- KEGG API failing? --> gseapy with offline gene sets125| +-- No, want cutoff-free analysis --> GSEA126| +-- Using R? --> clusterProfiler::gseKEGG()127| +-- Using Python? --> gseapy.prerank()128|129+-- Need to split by direction?130| +-- ORA --> YES, always split up/down (mandatory)131| +-- GSEA --> No split needed (direction encoded in ranking)132|133+-- KEGG API unreliable?134 +-- Try cached/pre-fetched data first135 +-- Fall back to gseapy offline databases136 +-- Use retry logic with short timeouts137```138139| Scenario | Recommended Approach | Rationale |140|----------|---------------------|-----------|141| Standard ORA with R | `clusterProfiler::enrichKEGG()`, split by direction | Most widely used, integrates with Bioconductor ecosystem |142| Standard ORA with Python | `gseapy.enrichr()` with KEGG_2021_Human | Offline gene sets avoid API dependency |143| Cutoff-free enrichment | GSEA via `gseKEGG()` or `gp.prerank()` | Captures subtle coordinated changes, no arbitrary threshold |144| KEGG API is down | Switch to gseapy offline databases | gseapy bundles KEGG gene sets locally |145| Comparing conditions | Run separate up/down enrichment per condition | Enables direction-aware set operations across conditions |146| Non-model organism | Verify organism code, use KEGGREST to check availability | Wrong code silently returns empty results |147148## Best Practices1491501. **Always split ORA by gene direction.** Run `enrichKEGG()` or `gp.enrichr()` separately for up-regulated and down-regulated genes. Combining them inflates the gene list, dilutes enrichment signal, and produces incorrect pathway counts. Report the union of significant pathways from both directions.1511522. **Specify the background universe explicitly.** Set the universe to all tested genes (the full set from your differential expression analysis), not just the significant ones. Omitting the universe defaults to all genes in the KEGG database, which inflates significance for well-studied pathways.1531543. **Pre-fetch and cache KEGG data before running enrichment.** Download pathway-gene mappings at the start of the analysis and save them locally. This avoids mid-analysis failures when the KEGG API becomes unresponsive and makes the analysis reproducible.1551564. **Report the numeric answer before resolving pathway names.** Once you have computed the count or list of significant pathway IDs, emit that result immediately. Resolving IDs to human-readable names via additional KEGG API calls is cosmetic and can timeout, losing the primary result.1571585. **Apply multiple testing correction consistently.** Use adjusted p-values (p.adjust < 0.05, typically BH method) rather than raw p-values. Both clusterProfiler and gseapy apply correction by default, but always verify the cutoff is on the adjusted value.1591606. **Verify gene ID format matches the organism.** Eukaryotic KEGG pathways expect Entrez gene IDs; bacterial species expect locus tags. A mismatch silently returns zero enriched pathways. Use `bitr()` in clusterProfiler or equivalent ID conversion if your input uses gene symbols.1611627. **Use gseapy as a fallback when clusterProfiler fails.** When `enrichKEGG()` fails due to KEGG API issues, gseapy's `enrichr()` function with bundled offline gene sets (e.g., `KEGG_2021_Human`) provides equivalent ORA results without any network dependency.163164## Common Pitfalls1651661. **Combining up-regulated and down-regulated genes into a single enrichment run.** Pathways with genes regulated in opposite directions cancel out, producing fewer significant pathways than the true count. Results from combined lists are unreliable. Example of the anti-pattern:167168 ```r169 # WRONG: combining up and down genes into one list170 all_sig_genes <- rownames(subset(res, padj < 0.05 & abs(log2FoldChange) > 1.5))171 ekegg <- enrichKEGG(gene = all_sig_genes, ...) # Will miss pathways172 ```173174 - *How to avoid*: Always split DEGs by direction before ORA. Run enrichment twice (once for up, once for down) and take the union of significant pathways.1751762. **Using the wrong KEGG organism code.** KEGG silently returns empty results for invalid or mismatched organism codes. This is especially common for bacterial species with multiple strain-specific codes (e.g., `pae` for PAO1 vs `pau` for PA14).177 - *How to avoid*: Confirm the organism code from the KEGG organism list before running enrichment. For bacteria, verify the specific strain code.1781793. **Gene ID type mismatch.** Providing gene symbols when KEGG expects Entrez IDs (or locus tags for bacteria) silently yields zero enriched pathways with no error message.180 - *How to avoid*: Check the expected ID type for your organism. Use `clusterProfiler::bitr()` or equivalent to convert gene symbols to Entrez IDs before enrichment.1811824. **Not handling KEGG API timeouts.** The KEGG REST API frequently times out, causing `enrichKEGG()` to fail mid-analysis. Without error handling, the entire analysis is lost.183 - *How to avoid*: Wrap KEGG API calls in retry logic with short timeouts (30 seconds). Pre-fetch pathway data at the start. Have gseapy as a fallback.1841855. **Delaying the answer to resolve pathway names.** Calling `keggGet()` to convert pathway IDs to human-readable names after computing results can timeout, losing the numeric answer entirely. Example of the anti-pattern:186187 ```r188 # BAD: answer delayed by name lookup that may hang189 result_ids <- setdiff(pathways_condA, pathways_condB)190 names <- keggGet(result_ids) # Can timeout -- answer never emitted191 count <- length(result_ids)192 ```193194 - *How to avoid*: Report pathway IDs and counts immediately. Resolve names only after the primary result is secured, inside a `tryCatch()` or try/except block.1951966. **Omitting the background universe.** Not specifying the universe parameter defaults to the entire KEGG gene database for that organism, inflating statistical significance for pathways containing well-annotated housekeeping genes.197 - *How to avoid*: Always pass `universe = rownames(res)` (all tested genes from the DE analysis) to `enrichKEGG()`.1981997. **Using raw p-values instead of adjusted p-values for filtering.** Reporting pathways with p < 0.05 without multiple testing correction dramatically increases false positives.200 - *How to avoid*: Always filter on `p.adjust < 0.05`. Verify that the column you are filtering is the adjusted value, not the raw p-value.201202## Workflow2032041. **Step 1: Prepare gene lists**205 - Filter significant DEGs from differential expression results (e.g., padj < 0.05, |log2FC| > 1.5)206 - Split into up-regulated and down-regulated gene sets207 - Convert gene IDs to the format expected by KEGG (Entrez IDs or locus tags)208209 ```r210 library(clusterProfiler)211212 # Filter significant DEGs213 sig_genes <- subset(res, padj < 0.05 & abs(log2FoldChange) > 1.5)214215 # MANDATORY: Split by direction BEFORE running enrichment216 up_genes <- rownames(subset(sig_genes, log2FoldChange > 0))217 dn_genes <- rownames(subset(sig_genes, log2FoldChange < 0))218219 cat("Up-regulated genes:", length(up_genes), "\n")220 cat("Down-regulated genes:", length(dn_genes), "\n")221 ```2222232. **Step 2: Pre-fetch KEGG data (recommended)**224 - Cache pathway-gene mappings locally before running enrichment225 - Decision point: If KEGG API is accessible, proceed with live queries. If not, switch to offline gene sets (Step 2b).226227 **R (KEGGREST package):**228 ```r229 library(KEGGREST)230 pathway_list <- tryCatch(231 keggList("pathway", organism_code),232 error = function(e) NULL233 )234 ```235236 **Python (requests with caching):**237 ```python238 import requests239 import json240 import os241242 cache_file = f"kegg_{organism_code}_pathways.json"243 if os.path.exists(cache_file):244 with open(cache_file) as f:245 pathway_map = json.load(f)246 else:247 resp = requests.get(248 f"https://rest.kegg.jp/list/pathway/{organism_code}", timeout=30249 )250 if resp.ok:251 pathway_map = dict(252 line.split("\t") for line in resp.text.strip().split("\n")253 )254 with open(cache_file, 'w') as f:255 json.dump(pathway_map, f)256 ```2572583. **Step 3: Run enrichment separately for each direction**259 - Run ORA twice: once for up-regulated genes, once for down-regulated genes260 - Always specify the universe (all tested genes)261262 **R (clusterProfiler):**263 ```r264 ekegg_up <- enrichKEGG(gene = up_genes, organism = organism_code,265 universe = rownames(res), pvalueCutoff = 0.05)266 ekegg_dn <- enrichKEGG(gene = dn_genes, organism = organism_code,267 universe = rownames(res), pvalueCutoff = 0.05)268269 up_pathways <- subset(as.data.frame(ekegg_up), p.adjust < 0.05)$ID270 dn_pathways <- subset(as.data.frame(ekegg_dn), p.adjust < 0.05)$ID271272 all_sig_pathways <- union(up_pathways, dn_pathways)273 cat("Significant pathways (up):", length(up_pathways), "\n")274 cat("Significant pathways (down):", length(dn_pathways), "\n")275 cat("Total unique significant pathways:", length(all_sig_pathways), "\n")276 ```277278 **Python (gseapy):**279 ```python280 import gseapy as gp281282 up_genes = sig_genes[sig_genes['log2FoldChange'] > 0].index.tolist()283 dn_genes = sig_genes[sig_genes['log2FoldChange'] < 0].index.tolist()284285 enr_up = gp.enrichr(gene_list=up_genes, gene_sets='KEGG_2021_Human',286 organism='human', outdir=None)287 enr_dn = gp.enrichr(gene_list=dn_genes, gene_sets='KEGG_2021_Human',288 organism='human', outdir=None)289 ```2902914. **Step 4: Report results immediately**292 - Emit pathway IDs and counts before attempting name resolution293 - Optionally resolve pathway names in a non-blocking manner294295 ```r296 result_ids <- setdiff(pathways_condA, pathways_condB)297 count <- length(result_ids)298 cat("Answer:", count, "pathways unique to condition A\n")299 cat("Pathway IDs:", paste(result_ids, collapse = ", "), "\n")300301 # Optional: resolve names (non-blocking)302 names <- tryCatch(keggGet(result_ids), error = function(e) NULL)303 ```3043055. **Step 5: Cross-condition comparison (if applicable)**306 - Run separate up/down enrichment for each condition (4 enrichKEGG calls total)307 - Compare pathway sets within the same direction308 - Report the union of direction-specific unique pathways309310 ```r311 # Condition A312 up_pathways_A <- subset(as.data.frame(ekegg_up_A), p.adjust < 0.05)$ID313 dn_pathways_A <- subset(as.data.frame(ekegg_dn_A), p.adjust < 0.05)$ID314315 # Condition B316 up_pathways_B <- subset(as.data.frame(ekegg_up_B), p.adjust < 0.05)$ID317 dn_pathways_B <- subset(as.data.frame(ekegg_dn_B), p.adjust < 0.05)$ID318319 # Find pathways unique to condition A in each direction320 unique_up <- setdiff(up_pathways_A, up_pathways_B)321 unique_dn <- setdiff(dn_pathways_A, dn_pathways_B)322323 # Union324 unique_to_A <- union(unique_up, unique_dn)325 cat("Pathways in A but not B:", length(unique_to_A), "\n")326 cat(" From up-regulated:", length(unique_up), "-",327 paste(unique_up, collapse = ", "), "\n")328 cat(" From down-regulated:", length(unique_dn), "-",329 paste(unique_dn, collapse = ", "), "\n")330 ```3313326. **Step 6: Handle API failures with retry logic**333 - If KEGG API calls fail, retry with timeout before falling back to offline data334335 ```r336 fetch_kegg_with_retry <- function(organism_code, max_retries = 3,337 timeout_sec = 30) {338 for (i in seq_len(max_retries)) {339 result <- tryCatch({340 R.utils::withTimeout(341 keggList("pathway", organism_code),342 timeout = timeout_sec343 )344 }, error = function(e) NULL)345 if (!is.null(result)) return(result)346 Sys.sleep(2)347 }348 warning("KEGG API unreachable after retries. Proceeding without pathway names.")349 return(NULL)350 }351 ```352353## Further Reading354355- [KEGG: Kyoto Encyclopedia of Genes and Genomes](https://www.kegg.jp/) -- Official KEGG database with pathway maps, organism lists, and REST API documentation356- [clusterProfiler: an R package for comparing biological themes among gene clusters](https://doi.org/10.1089/omi.2011.0118) -- Original publication by Guangchuang Yu describing the enrichKEGG and gseKEGG functions357- [gseapy documentation](https://gseapy.readthedocs.io/) -- Python package for gene set enrichment analysis with offline KEGG gene set support358- [KEGG REST API reference](https://rest.kegg.jp/kegg/rest_api.html) -- Technical documentation for programmatic access to KEGG pathway data359360## Related Skills361362- `gseapy-gene-enrichment` -- Python-based gene set enrichment analysis; use as a fallback when clusterProfiler KEGG API calls fail, or as the primary tool for Python-based workflows363- `deseq2-differential-expression` / `pydeseq2-differential-expression` -- Upstream differential expression analysis that produces the DEG lists used as input to KEGG pathway enrichment