tooluniverse-pharmacogenomics

What this skill does

## COMPUTE, DON'T DESCRIBE
When analysis requires computation (statistics, data processing, scoring, enrichment), write and run Python code via Bash. Don't describe what you would do — execute it and report actual results. Use ToolUniverse tools to retrieve data, then Python (pandas, scipy, statsmodels, matplotlib) to analyze it.

# Pharmacogenomics (PGx) Research Skill

Systematic PGx analysis: resolve gene-drug pairs, retrieve CPIC dosing guidelines, annotate alleles and variants with PharmGKB, check FDA PGx biomarker labeling, and generate evidence-graded clinical recommendations.

## When to Use

- "What CPIC guidelines exist for CYP2D6?"
- "Get dosing recommendations for codeine based on CYP2D6 poor metabolizer status"
- "Which drugs have FDA pharmacogenomic biomarkers for CYP2C19?"
- "Find PharmGKB clinical annotations for rs1799853"
- "Is this patient's CYP2D6 genotype relevant to tamoxifen dosing?"
- "What is the functional status of CYP2D6*4?"
- "List all CPIC level A gene-drug pairs for CYP2D6"

## Workflow Overview

```
Input (gene/drug/variant/phenotype)
  |
  v
Phase 0: Disambiguation (resolve gene symbols, drug names, rsIDs)
  |
  v
Phase 1: Gene-Drug Pair Identification (CPIC pairs + evidence levels)
  |
  v
Phase 2: Guideline & Dosing Retrieval (CPIC recommendations + PharmGKB)
  |
  v
Phase 3: Allele & Variant Annotation (star alleles, function, activity scores)
  |
  v
Phase 4: FDA Biomarker Labeling (regulatory PGx status)
  |
  v
Phase 5: Cross-Database Enrichment (EpiGraphDB, DGIdb, OpenTargets PGx)
  |
  v
Phase 6: Report (evidence-graded clinical summary)
```

---

## Phase 0: Disambiguation

Resolve user input to canonical identifiers before querying PGx databases.

**PharmGKB_search_genes**: `query` (string REQUIRED, e.g., "CYP2D6"). Returns `{status, data: [{id, symbol, name}]}`.
- Use to get PharmGKB gene accession ID (e.g., "PA128" for CYP2D6).

**PharmGKB_search_drugs**: `query` (string REQUIRED, e.g., "codeine"). Returns `{status, data: [{id, name, types}]}`.
- Use to get PharmGKB chemical ID (e.g., "PA449088" for codeine).

**PharmGKB_search_variants**: `query` (string REQUIRED, rsID e.g., "rs1799853"). Returns `{status, data: [{id, symbol, changeClassification, clinicalSignificance}]}`.
- Use to resolve rsIDs and find PharmGKB annotation IDs.

**CPIC_get_drug_info**: `name` (string REQUIRED, lowercase, e.g., "codeine"). Returns drug identifiers including `drugid`, `rxnormid`, `drugbankid`, `atcid`, `guidelineid`, and `flowchart` URL.
- Also resolves drug names: can be used to find the `guidelineid` directly from a drug name.

**CPIC_get_gene_info**: `symbol` (string REQUIRED, e.g., "CYP2D6"). Returns gene coordinates, PharmGKB/HGNC/Ensembl IDs, `lookupmethod` (ACTIVITY_SCORE or PHENOTYPE), and allele frequency methodology.

---

## Phase 1: Identify Gene-Drug Pairs

**CPIC_search_gene_drug_pairs**: `gene_symbol` (string), `cpiclevel` ("A"/"B"/"C"/"D"), `limit` (int, default 50). Returns `{status, data: [{genesymbol, drugid, cpiclevel, guidelineid, pgxtesting, clinpgxlevel, usedforrecommendation}]}`.
- Primary tool for filtering by evidence level. CPIC levels: A = strongest/actionable, B = moderate, C = informational, D = insufficient.
- **PostgREST auto-normalization**: Accepts plain gene symbols (e.g., "CYP2D6") -- the tool auto-prepends `eq.` prefix.
- Also accepts aliases: `gene` or `gene_symbol` both resolve to `genesymbol`.

**CPIC_get_gene_drug_pairs**: `genesymbol` (string REQUIRED). Returns ALL pairs for one gene including `drug: {name}`, `citations`, `guidelineid`.
- Returns drug names in response (unlike search which returns RxNorm IDs only).

**CPIC_list_drugs**: No params. Returns all drugs with guideline IDs. Use for browsing.

**CPIC_list_pgx_genes**: No params. Returns all PGx genes curated by CPIC with `symbol`, `lookupmethod`, `ensemblid`.

**EpiGraphDB_get_gene_drug_associations**: `gene_name` (string REQUIRED, e.g., "CYP2D6"). Returns `{status, data: {gene_drug_associations: [{gene, drug, source, pharmgkb_evidence, cpic_level, pgx_on_fda_label, guideline}]}}`.
- Aggregates CPIC + PharmGKB evidence with FDA label status in one call. Good for quick overview.

### Finding Guideline IDs

Don't memorize guideline IDs. Use `CPIC_list_guidelines(gene="CYP2D6")` or `CPIC_list_guidelines(drug="codeine")` to discover them. Each result includes both the numeric `id` (for `CPIC_get_recommendations`) and the `clinpgxid` string (for `PharmGKB_get_dosing_guidelines`).

---

## Phase 2: Retrieve Dosing Guidelines

**CPIC_get_recommendations** (CPICGetRecommendationsTool): `guideline_id` (integer, OR `drug`/`drug_name` string for auto-resolution), `limit` (int, default 50), `offset` (int). Returns `{status, data: {guideline_id, recommendations: [{drugrecommendation, classification, phenotypes, implications, activityscore, lookupkey, population, drug: {name}}], count}}`.
- Preferred usage: `CPIC_get_recommendations(drug="codeine", limit=50)` — auto-resolves drug name to guideline_id via CPIC API, and filters within multi-drug guidelines (e.g., CYP2D6 opioid guideline covers codeine + tramadol) using RxNorm ID matching.
- `classification`: "Strong", "Moderate", or "Optional". `phenotypes`: maps gene → metabolizer phenotype. `activityscore`: maps gene → activity score.
- Fallback: `CPIC_get_drug_info(name="codeine")` to extract guidelineid, then `CPIC_get_recommendations(guideline_id=100416, limit=50)`.

**CPIC_get_drug_info**: `name` (string REQUIRED, lowercase, e.g., "codeine"). Returns `{status, data: [{drugid, guidelineid, flowchart, rxnormid, drugbankid}]}`.
- Key shortcut: returns `guidelineid` directly. Still useful for extracting DrugBank/ATC IDs.

**PharmGKB_get_dosing_guidelines**: `guideline_id` (string REQUIRED -- use `clinpgxid` from CPIC_list_guidelines, e.g., "PA166251445"). Returns `{status, data: {id, name, level, literature: [{title, crossReferences}], link}}`.
- Provides CPIC guideline metadata, literature citations, and link to full guideline.

**CPIC_list_guidelines**: `gene` (string, optional), `drug` (string, optional). Returns `{status, data: [{id, name, url, genes, clinpgxid}]}`. Returns all ~29 guidelines; supports built-in filtering by gene/drug.
- Use this to discover `clinpgxid` values for PharmGKB_get_dosing_guidelines.

> **Note**: `PharmGKB_get_clinical_annotations` requires an `annotation_id` (e.g., "1447954390"). To discover annotation IDs, use `PharmGKB_search_variants(query=rsID)` first, then extract annotation IDs from the results.

### Gotchas

- **Warfarin** (guideline 100425): Algorithm-based dosing; `CPIC_get_recommendations` returns 0 rows. Direct users to CPIC website or PharmGKB.
- **PharmGKB guideline linking**: Use `clinpgxid` (e.g., "PA166251445"), NOT `pharmgkbid` (old format returns 404).
- **Multi-gene guidelines**: TCA guideline (100414) covers both CYP2D6 and CYP2C19; recommendations have phenotype combinations.
- **Drug name case**: `CPIC_get_drug_info` requires lowercase. `CPIC_get_recommendations` with `drug=` uses ilike matching (case-insensitive).
- **CPIC_get_recommendations returns wrapped data**: Response is `{status, data: {guideline_id, recommendations: [...], count}}` -- recommendations are nested under `data.recommendations`.

---

## Phase 3: Allele & Variant Annotation

**CPIC_get_alleles**: `genesymbol` (string REQUIRED), `limit` (int, default 50). Returns `{status, data: [{name, clinicalfunctionalstatus, activityvalue, functionalstatus}]}`.
- Use `clinicalfunctionalstatus` (not `functionalstatus` which may be null). Values: "Normal function", "Decreased function", "No function", "Increased function", "Uncertain function", "Unknown function".
- `activityvalue`: numeric string (e.g., "1.0", "0.5", "0.0") or "n/a".

**PharmGKB_search_variants**: `query` (string REQUIRED, rsID). Returns variant classification and clinical significance.

**PharmGKB_get_clinical_annotations**: `annotation_id` (string REQUIRED, e.g., "1447954390"). Returns `{status, data: {