SkillAgentSearch skills...

kegg-pathway-analysis

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.

Install / Use

npx skills add jaechang-hits/SciAgent-Skills --skill kegg-pathway-analysis

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

89/100

Supported Platforms

Universal

Our assessment of kegg-pathway-analysis

kegg-pathway-analysis scores 89/100 on our quality scale, 1734th of 4,716 Development & Engineering skills we index (top 37%).

Its SKILL.md is 19 KB long, well organised into 14 sections with 2 code examples: a thorough specification that gives an agent plenty to work with.

It has 367 GitHub stars, a meaningful sign that others use it.

Substance
30/30
Structure
18/20
Description
15/15
Adoption
11/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 3 months ago, so kegg-pathway-analysis is actively maintained.
  • Our last check on 2026-10-31 found the source still online.
  • No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
  • Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-06. Automated pattern scan on 2026-10-05. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

kegg-pathway-analysis compared with similar skills

All 4 of these similar skills score higher than kegg-pathway-analysis; compare them before choosing.

SkillScoreStarsUpdatedFormat
kegg-pathway-analysis (this skill)by jaechang-hits893673mo agoSKILL.md
taste-skillby Leonxlnx100118.9k11d agoCLAUDE.md
Agent-Reachby Panniantong100113.3k12d agoCLAUDE.md
hyperframesby heygen-com10087.1ktodayCLAUDE.md
headroomby headroomlabs-ai10080.2ktodayCLAUDE.md

Frequently asked questions

How do I install kegg-pathway-analysis?
Run npx skills add jaechang-hits/SciAgent-Skills --skill kegg-pathway-analysis. The install tabs above show the steps for each supported agent.
Which AI agents does kegg-pathway-analysis work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is kegg-pathway-analysis safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is kegg-pathway-analysis still maintained?
The repository was last updated about 3 months ago, so kegg-pathway-analysis is actively maintained.

name: kegg-pathway-analysis description: "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." license: CC-BY-4.0

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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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
    

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars367
CategoryDevelopment
Updated2mo ago
Forks36

Languages

Python

Trust signals

88/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium