tooluniverse-kegg-disease-drug

What this skill does

# 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)

| Tool | Key Params | Returns |
|------|-----------|---------|
| KEGG_search_disease | `keyword` | Disease entries matching keyword |
| KEGG_get_disease | `disease_id` (e.g., "H00004") | Disease details: genes, drugs, pathways |
| KEGG_get_disease_genes | `disease_id` | All genes for a disease |
| KEGG_search_drug | `keyword` | Drug entries matching keyword |
| KEGG_get_drug | `drug_id` (e.g., "D00123") | Drug details: targets, pathways, metabolism |
| KEGG_get_drug_targets | `drug_id` | Molecular targets for a drug |
| KEGG_search_network | `keyword` | Network entries (disease-gene-drug) |
| KEGG_get_network | `network_id` | Network details and relationships |
| KEGG_search_variant | `keyword` | Variant entries matching keyword |
| KEGG_get_variant | `variant_id` | Variant details and disease associations |
| KEGG_convert_ids | `source_db`, `target_db`, `ids` | Convert identifiers between KEGG and external databases (e.g., NCBI Gene ↔ KEGG gene IDs, UniProt ↔ KEGG) |
| KEGG_link_entries | `target_db`, `source_db_or_ids` | Find cross-database relationships (e.g., all genes linked to a pathway, all drugs linked to a disease) |

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

```python
# 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.

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

### Phase 3: Drug Search

Find KEGG drugs by name, target, or keyword.

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

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

### Phase 5: Network & Variant Context

Explore disease-gene-drug networks and variant annotations.

```python
# 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

```python
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 between KEGG identifiers and external databases before or after lookups:

```python
# Convert NCBI Gene IDs to KEGG gene IDs for human (hsa)
result = tu.tools.KEGG_convert_ids(source_db="ncbi-geneid", target_db="hsa", ids=["672", "675"])

# Convert UniProt accessions to KEGG entries
result = tu.tools.KEGG_convert_ids(source_db="up", target_db="hsa", ids=["P38398"])
```

Use `KEGG_link_entries` to retrieve relationships between KEGG databases:

```python
# Find all KEGG pathway IDs that contain a given gene
result = tu.tools.KEGG_link_entries(target_db="pathway", source_db_or_ids="hsa:7157")

# Find all genes linked to a specific pathway
result = tu.tools.KEGG_link_entries(target_db="hsa", source_db_or_ids="path:hsa05210")
```

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

| Grade | Criteria | Example |
|-------|----------|---------|
| **Strong** | KEGG disease entry with curated gene list, drug with confirmed target, pathway mechanistically linked | H00031 (breast cancer) with BRCA1/BRCA2 genes, D09996 (vemurafenib) targeting BRAF |
| **Moderate** | Disease-gene link in KEGG but no drug-target validation, or network entry without variant data | KEGG disease entry lists gene, but drug targets are inferred from pathway membership |
| **Weak** | Keyword search hit only, no curated disease-gene-drug relationship in KEGG | Drug found by name search but not linked to the disease in KEGG network |
| **Insufficient** | No KEGG entries found, or only cross-database ID conversion available | Rare disease not curated in KEGG Disease |

### 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-le