mims-harvard/tooluniverse/tooluniverse-kegg-disease-drug

KEGG Disease-Drug-Variant Research

Systematic exploration of disease-drug-variant relationships using KEGG's curated databases.

Reasoning Strategy

KEGG maps diseases to pathways and drugs to targets, but the real value is in the connections — which pathways link a disease gene to a drug target? This is a network question, not a simple lookup. A gene appearing in a KEGG disease entry has been editorially reviewed as mechanistically relevant; a drug entry with a confirmed target is more reliable than one inferred from pathway co-membership. When using KEGG for drug repurposing, always ask: is the drug-target relationship direct (the drug binds the gene product) or indirect (the drug affects a pathway that contains the gene)? Direct relationships are far stronger evidence. KEGG coverage is not exhaustive — absence from KEGG does not mean absence of biological involvement; complement with Reactome, WikiPathways, or CTD for broader coverage. ID namespace differences are a frequent source of errors: KEGG uses its own gene IDs (e.g., hsa:7157 for TP53), so always convert external IDs before querying KEGG-specific tools.

LOOK UP DON'T GUESS: Do not assume KEGG disease IDs, drug IDs, or gene IDs from memory — always search first with KEGG_search_disease, KEGG_search_drug, or KEGG_convert_ids. Do not assume which pathways link a disease gene to a drug; use KEGG_link_entries and KEGG_get_network to retrieve the actual connections.

When to Use

• "What genes are associated with [disease] in KEGG?"
• "Find KEGG drugs targeting [gene/pathway]"
• "What variants are linked to [disease] in KEGG?"
• "Show the KEGG disease-gene-drug network for [condition]"
• "Find drugs targeting BRAF variants in cancer"

Tool Inventory (12 tools)

Workflow

Phase 1: Disease Lookup -> Phase 2: Disease Genes -> Phase 3: Drug Search
  -> Phase 4: Drug Targets -> Phase 5: Network/Variant Context -> Report

Phase 1: Disease Lookup

Search and retrieve KEGG disease entries.

# Search for cancer-related diseases
diseases = tu.tools.KEGG_search_disease(keyword="breast cancer")
# Get details for a specific disease
disease = tu.tools.KEGG_get_disease(disease_id="H00031")

Phase 2: Disease Genes

Get genes associated with a KEGG disease entry.

genes = tu.tools.KEGG_get_disease_genes(disease_id="H00031")

Phase 3: Drug Search

Find KEGG drugs by name, target, or keyword.

drugs = tu.tools.KEGG_search_drug(keyword="vemurafenib")
drug_detail = tu.tools.KEGG_get_drug(drug_id="D09996")

Phase 4: Drug Targets

Get molecular targets for a drug.

targets = tu.tools.KEGG_get_drug_targets(drug_id="D09996")

Phase 5: Network & Variant Context

Explore disease-gene-drug networks and variant annotations.

# Search networks linking disease, genes, and drugs
networks = tu.tools.KEGG_search_network(keyword="BRAF melanoma")
network = tu.tools.KEGG_get_network(network_id="N00001")
# Search and get variant details
variants = tu.tools.KEGG_search_variant(keyword="BRAF V600E")
variant = tu.tools.KEGG_get_variant(variant_id="hsa:BRAF")

Example Workflow: Find Drugs Targeting BRAF Variants in Cancer

from tooluniverse import ToolUniverse
tu = ToolUniverse()
tu.load_tools()
# 1. Find BRAF-related diseases
diseases = tu.tools.KEGG_search_disease(keyword="BRAF")
# 2. Get disease genes for melanoma
genes = tu.tools.KEGG_get_disease_genes(disease_id="H00038")
# 3. Search for BRAF-targeting drugs
drugs = tu.tools.KEGG_search_drug(keyword="BRAF inhibitor")
# 4. Get targets for vemurafenib
targets = tu.tools.KEGG_get_drug_targets(drug_id="D09996")
# 5. Get BRAF variant info
variants = tu.tools.KEGG_search_variant(keyword="BRAF V600E")
# 6. Explore disease-gene-drug network
networks = tu.tools.KEGG_search_network(keyword="BRAF melanoma")

ID Conversion & Cross-Linking

Use KEGG_convert_ids to map KEGG identifiers to external databases (it converts KEGG → external only):

# Convert KEGG human gene IDs to UniProt accessions (join several IDs with '+')
result = tu.tools.KEGG_convert_ids(kegg_id="hsa:672+hsa:675", target_db="uniprot")
# result['data'] -> [{"kegg_id": "hsa:672", "external_id": "up:P38398"}, ...]
# Convert a KEGG gene ID to its NCBI Gene ID
result = tu.tools.KEGG_convert_ids(kegg_id="hsa:672", target_db="ncbi-geneid")

For the reverse direction, KEGG human gene IDs are simply hsa: plus the NCBI Gene ID (NCBI Gene 672 is hsa:672); there is no external → KEGG conversion tool.

Use KEGG_link_entries to retrieve relationships between KEGG databases:

# Find all KEGG pathway IDs that contain a given gene
result = tu.tools.KEGG_link_entries(source="hsa:7157", target="pathway")
# Find all genes linked to a specific pathway
result = tu.tools.KEGG_link_entries(source="hsa05210", target="hsa")

These tools are especially useful when you have external IDs (Entrez Gene, UniProt, ChEMBL) and need to bridge into KEGG's namespace, or when you want a complete gene-pathway or drug-disease adjacency list.

Integration with Other Skills

• Pathway details: Use tooluniverse-systems-biology for Reactome/WikiPathways cross-ref
• Drug mechanisms: Use tooluniverse-drug-mechanism-research for ChEMBL/DailyMed MOA
• Clinical variants: Use tooluniverse-cancer-variant-interpretation for CIViC/ClinVar
• Drug safety: Use tooluniverse-adverse-event-detection for FAERS data

Reasoning Framework for Result Interpretation

Evidence Grading

Interpretation Guidance

• KEGG pathway significance: KEGG pathways are manually curated maps of molecular interactions. A gene appearing in a KEGG disease pathway has been editorially reviewed as relevant to that disease mechanism. However, KEGG coverage is not exhaustive -- absence from KEGG does not mean absence of involvement. Cross-reference with Reactome or WikiPathways for broader coverage.
• Disease-drug network interpretation: KEGG Network entries (N-codes) link diseases, genes, and drugs in mechanistic triangles. A drug targeting a gene in a disease network has a curated rationale for therapeutic relevance. The network structure distinguishes direct targets (drug binds gene product) from pathway-level connections (drug affects pathway containing the gene). Prioritize direct target relationships for drug repurposing hypotheses.
• Variant impact assessment: KEGG Variant entries are curated for clinical significance (often cancer driver mutations). A variant listed in KEGG with a linked drug entry indicates an established pharmacogenomic or precision oncology relationship (e.g., BRAF V600E linked to vemurafenib). Variants not in KEGG may still be clinically relevant -- cross-reference with ClinVar and CIViC.
• ID conversion caveat: KEGG uses its own gene ID namespace (e.g., hsa:7157 for TP53). Human KEGG gene IDs are hsa: plus the NCBI Gene ID; KEGG_convert_ids only maps KEGG IDs to external IDs (UniProt, NCBI Gene), so resolve UniProt accessions to NCBI Gene IDs first with another tool. Failed conversions may indicate the gene is not in KEGG's curated set.
• Drug entry completeness: KEGG Drug entries vary in detail. Approved drugs typically have full target, pathway, and metabolism information. Investigational compounds may have partial entries. Check the drug's "Target" and "Pathway" fields for completeness before drawing conclusions.

Synthesis Questions

1. Does the KEGG disease entry list the gene of interest with a direct mechanistic role, or is the gene only peripherally connected through a shared pathway?
2. For drug-target relationships, is the target confirmed by KEGG Network (direct link), or inferred from pathway co-membership?
3. Are there KEGG variant entries linking specific mutations to drug response, supporting precision medicine applications?
4. Does the KEGG disease-gene-drug network for the condition align with evidence from other curated sources (CIViC, OncoKB, DrugBank)?
5. If KEGG has limited entries for the query, which complementary databases (Reactome, WikiPathways, CTD) should be consulted to fill gaps?

Output

Markdown report with:

1. Disease summary (KEGG ID, name, associated genes/pathways)
2. Gene list with KEGG gene IDs and symbols
3. Drug candidates with targets and mechanisms
4. Network relationships (disease-gene-drug triangles)
5. Variant annotations if available