Clinpgx Database

{
  "description": "\"Access ClinPGx pharmacogenomics data (successor to PharmGKB). Query gene-drug interactions, CPIC guidelines, allele functions, for precision medicine and genotype-guided dosing decisions.\"",
  "references": {
    "files": [
      "references/api_reference.md"
    ]
  },
  "content": "### 1. Gene Queries\r\n\r\n**Retrieve gene information** including function, clinical annotations, and pharmacogenomic significance:\r\n\r\n```python\r\nimport requests\r\n\r\nresponse = requests.get(\"https://api.clinpgx.org/v1/gene/CYP2D6\")\r\ngene_data = response.json()\r\n\r\nresponse = requests.get(\"https://api.clinpgx.org/v1/gene\",\r\n                       params={\"q\": \"CYP\"})\r\ngenes = response.json()\r\n```\r\n\r\n**Key pharmacogenes**:\r\n- **CYP450 enzymes**: CYP2D6, CYP2C19, CYP2C9, CYP3A4, CYP3A5\r\n- **Transporters**: SLCO1B1, ABCB1, ABCG2\r\n- **Other metabolizers**: TPMT, DPYD, NUDT15, UGT1A1\r\n- **Receptors**: OPRM1, HTR2A, ADRB1\r\n- **HLA genes**: HLA-B, HLA-A\r\n\r\n### 2. Drug and Chemical Queries\r\n\r\n**Retrieve drug information** including pharmacogenomic annotations and mechanisms:\r\n\r\n```python\r\nresponse = requests.get(\"https://api.clinpgx.org/v1/chemical/PA448515\")  # Warfarin\r\ndrug_data = response.json()\r\n\r\nresponse = requests.get(\"https://api.clinpgx.org/v1/chemical\",\r\n                       params={\"name\": \"warfarin\"})\r\ndrugs = response.json()\r\n```\r\n\r\n**Drug categories with pharmacogenomic significance**:\r\n- Anticoagulants (warfarin, clopidogrel)\r\n- Antidepressants (SSRIs, TCAs)\r\n- Immunosuppressants (tacrolimus, azathioprine)\r\n- Oncology drugs (5-fluorouracil, irinotecan, tamoxifen)\r\n- Cardiovascular drugs (statins, beta-blockers)\r\n- Pain medications (codeine, tramadol)\r\n- Antivirals (abacavir)\r\n\r\n### 3. Gene-Drug Pair Queries\r\n\r\n**Access curated gene-drug relationships** with clinical annotations:\r\n\r\n```python\r\nresponse = requests.get(\"https://api.clinpgx.org/v1/geneDrugPair\",\r\n                       params={\"gene\": \"CYP2D6\", \"drug\": \"codeine\"})\r\npair_data = response.json()\r\n\r\nresponse = requests.get(\"https://api.clinpgx.org/v1/geneDrugPair\",\r\n                       params={\"gene\": \"CYP2C19\"})\r\nall_pairs = response.json()\r\n```\r\n\r\n**Clinical annotation sources**:\r\n- CPIC (Clinical Pharmacogenetics Implementation Consortium)\r\n- DPWG (Dutch Pharmacogenetics Working Group)\r\n- FDA (Food and Drug Administration) labels\r\n- Peer-reviewed literature summary annotations\r\n\r\n### 4. CPIC Guidelines\r\n\r\n**Access evidence-based clinical practice guidelines**:\r\n\r\n```python\r\nresponse = requests.get(\"https://api.clinpgx.org/v1/guideline/PA166104939\")\r\nguideline = response.json()\r\n\r\nresponse = requests.get(\"https://api.clinpgx.org/v1/guideline\",\r\n                       params={\"source\": \"CPIC\"})\r\nguidelines = response.json()\r\n```\r\n\r\n**CPIC guideline components**:\r\n- Gene-drug pairs covered\r\n- Clinical recommendations by phenotype\r\n- Evidence levels and strength ratings\r\n- Supporting literature\r\n- Downloadable PDFs and supplementary materials\r\n- Implementation considerations\r\n\r\n**Example guidelines**:\r\n- CYP2D6-codeine (avoid in ultra-rapid metabolizers)\r\n- CYP2C19-clopidogrel (alternative therapy for poor metabolizers)\r\n- TPMT-azathioprine (dose reduction for intermediate/poor metabolizers)\r\n- DPYD-fluoropyrimidines (dose adjustment based on activity)\r\n- HLA-B*57:01-abacavir (avoid if positive)\r\n\r\n### 5. Allele and Variant Information\r\n\r\n**Query allele function and frequency data**:\r\n\r\n```python\r\nresponse = requests.get(\"https://api.clinpgx.org/v1/allele/CYP2D6*4\")\r\nallele_data = response.json()\r\n\r\nresponse = requests.get(\"https://api.clinpgx.org/v1/allele\",\r\n                       params={\"gene\": \"CYP2D6\"})\r\nalleles = response.json()\r\n```\r\n\r\n**Allele information includes**:\r\n- Functional status (normal, decreased, no function, increased, uncertain)\r\n- Population frequencies across ethnic groups\r\n- Defining variants (SNPs, indels, CNVs)\r\n- Phenotype assignment\r\n- References to PharmVar and other nomenclature systems\r\n\r\n**Phenotype categories**:\r\n- **Ultra-rapid metabolizer** (UM): Increased enzyme activity\r\n- **Normal metabolizer** (NM): Normal enzyme activity\r\n- **Intermediate metabolizer** (IM): Reduced enzyme activity\r\n- **Poor metabolizer** (PM): Little to no enzyme activity\r\n\r\n### 6. Variant Annotations\r\n\r\n**Access clinical annotations for specific genetic variants**:\r\n\r\n```python\r\nresponse = requests.get(\"https://api.clinpgx.org/v1/variant/rs4244285\")\r\nvariant_data = response.json()\r\n\r\nresponse = requests.get(\"https://api.clinpgx.org/v1/variant\",\r\n                       params={\"chromosome\": \"10\", \"position\": \"94781859\"})\r\nvariants = response.json()\r\n```\r\n\r\n**Variant data includes**:\r\n- rsID and genomic coordinates\r\n- Gene and functional consequence\r\n- Allele associations\r\n- Clinical significance\r\n- Population frequencies\r\n- Literature references\r\n\r\n### 7. Clinical Annotations\r\n\r\n**Retrieve curated literature annotations** (formerly PharmGKB clinical annotations):\r\n\r\n```python\r\nresponse = requests.get(\"https://api.clinpgx.org/v1/clinicalAnnotation\",\r\n                       params={\"gene\": \"CYP2D6\"})\r\nannotations = response.json()\r\n\r\nresponse = requests.get(\"https://api.clinpgx.org/v1/clinicalAnnotation\",\r\n                       params={\"evidenceLevel\": \"1A\"})\r\nhigh_evidence = response.json()\r\n```\r\n\r\n**Evidence levels** (from highest to lowest):\r\n- **Level 1A**: High-quality evidence, CPIC/FDA/DPWG guidelines\r\n- **Level 1B**: High-quality evidence, not yet guideline\r\n- **Level 2A**: Moderate evidence from well-designed studies\r\n- **Level 2B**: Moderate evidence with some limitations\r\n- **Level 3**: Limited or conflicting evidence\r\n- **Level 4**: Case reports or weak evidence\r\n\r\n### 8. Drug Labels\r\n\r\n**Access pharmacogenomic information from drug labels**:\r\n\r\n```python\r\nresponse = requests.get(\"https://api.clinpgx.org/v1/drugLabel\",\r\n                       params={\"drug\": \"warfarin\"})\r\nlabels = response.json()\r\n\r\nresponse = requests.get(\"https://api.clinpgx.org/v1/drugLabel\",\r\n                       params={\"source\": \"FDA\"})\r\nfda_labels = response.json()\r\n```\r\n\r\n**Label information includes**:\r\n- Testing recommendations\r\n- Dosing guidance by genotype\r\n- Warnings and precautions\r\n- Biomarker information\r\n- Regulatory source (FDA, EMA, PMDA, etc.)\r\n\r\n### 9. Pathways\r\n\r\n**Explore pharmacokinetic and pharmacodynamic pathways**:\r\n\r\n```python\r\nresponse = requests.get(\"https://api.clinpgx.org/v1/pathway/PA146123006\")  # Warfarin pathway\r\npathway_data = response.json()\r\n\r\n\r\n### Rate Limit Compliance\r\n\r\n```python\r\nimport time\r\n\r\ndef rate_limited_request(url, params=None, delay=0.5):\r\n    \"\"\"Make API request with rate limiting (2 req/sec max)\"\"\"\r\n    response = requests.get(url, params=params)\r\n    time.sleep(delay)  # Wait 0.5 seconds between requests\r\n    return response\r\n\r\ngenes = [\"CYP2D6\", \"CYP2C19\", \"CYP2C9\"]\r\nfor gene in genes:\r\n    response = rate_limited_request(\r\n        \"https://api.clinpgx.org/v1/gene/\" + gene\r\n    )\r\n    data = response.json()\r\n```\r\n\r\n### Error Handling\r\n\r\n```python\r\ndef safe_api_call(url, params=None, max_retries=3):\r\n    \"\"\"API call with error handling and retries\"\"\"\r\n    for attempt in range(max_retries):\r\n        try:\r\n            response = requests.get(url, params=params, timeout=10)\r\n\r\n            if response.status_code == 200:\r\n                return response.json()\r\n            elif response.status_code == 429:\r\n                # Rate limit exceeded\r\n                wait_time = 2 ** attempt  # Exponential backoff\r\n                print(f\"Rate limit hit. Waiting {wait_time}s...\")\r\n                time.sleep(wait_time)\r\n            else:\r\n                response.raise_for_status()\r\n\r\n        except requests.exceptions.RequestException as e:\r\n            print(f\"Attempt {attempt + 1} failed: {e}\")\r\n            if attempt == max_retries - 1:\r\n                raise\r\n            time.sleep(1)\r\n```\r\n\r\n### Caching Results\r\n\r\n```python\r\nimport json\r\nfrom pathlib import Path\r\n\r\ndef cached_query(cache_file, api_func, *args, **kwargs):\r\n    \"\"\"Cache API results to avoid repeated queries\"\"\"\r\n    cache_path = Path(cache_file)\r\n\r\n    if cache_path.exists():\r\n        with open(cache_path) as f:\r\n            return json.load(f)\r\n\r\n    result = api_func(*args, **kwargs)\r\n\r\n    with open(cache_path, 'w') as f:\r\n        json.dump(result, f, indent=2)\r\n\r\n    return result\r\n\r\n\r\n### Pre-emptive Pharmacogenomic Testing\r\n\r\nQuery all clinically actionable gene-drug pairs to guide panel selection:\r\n\r\n```python\r\nresponse = requests.get(\"https://api.clinpgx.org/v1/geneDrugPair\",\r\n                       params={\"cpicLevel\": \"A\"})  # Level A recommendations\r\nactionable_pairs = response.json()\r\n```\r\n\r\n### Medication Therapy Management\r\n\r\nReview patient medications against known genotypes:\r\n\r\n```python\r\npatient_genes = {\"CYP2C19\": \"*1/*2\", \"CYP2D6\": \"*1/*1\", \"SLCO1B1\": \"*1/*5\"}\r\nmedications = [\"clopidogrel\", \"simvastatin\", \"escitalopram\"]\r\n\r\nfor med in medications:\r\n    for gene in patient_genes:\r\n        response = requests.get(\"https://api.clinpgx.org/v1/geneDrugPair\",\r\n                               params={\"gene\": gene, \"drug\": med})\r\n        # Check for interactions and dosing guidance\r\n```\r\n\r\n### Clinical Trial Eligibility\r\n\r\nScreen for pharmacogenomic contraindications:\r\n\r\n```python\r\nresponse = requests.get(\"https://api.clinpgx.org/v1/geneDrugPair\",\r\n                       params={\"gene\": \"HLA-B\", \"drug\": \"abacavir\"})\r\npair_info = response.json()",
  "name": "clinpgx-database",
  "id": "scientific-db-clinpgx-database",
  "sections": {
    "Common Use Cases": "```",
    "Additional Resources": "- **ClinPGx website**: https://www.clinpgx.org/\r\n- **ClinPGx Blog**: https://blog.clinpgx.org/\r\n- **API documentation**: https://api.clinpgx.org/\r\n- **CPIC website**: https://cpicpgx.org/\r\n- **PharmCAT**: https://pharmcat.clinpgx.org/\r\n- **ClinGen**: https://clinicalgenome.org/\r\n- **Contact**: api@clinpgx.org (for substantial API use)",
    "PharmDOG Tool": "PharmDOG (formerly DDRx) is ClinPGx's clinical decision support tool for interpreting pharmacogenomic test results:\r\n\r\n**Key features**:\r\n- **Phenoconversion calculator**: Adjusts phenotype predictions for drug-drug interactions affecting CYP2D6\r\n- **Custom genotypes**: Input patient genotypes to get phenotype predictions\r\n- **QR code sharing**: Generate shareable patient reports\r\n- **Flexible guidance sources**: Select which guidelines to apply (CPIC, DPWG, FDA)\r\n- **Multi-drug analysis**: Assess multiple medications simultaneously\r\n\r\n**Access**: Available at https://www.clinpgx.org/pharmacogenomic-decision-support\r\n\r\n**Use cases**:\r\n- Clinical interpretation of PGx panel results\r\n- Medication review for patients with known genotypes\r\n- Patient education materials\r\n- Point-of-care decision support",
    "Query Workflow": "### Workflow 1: Clinical Decision Support for Drug Prescription\r\n\r\n1. **Identify patient genotype** for relevant pharmacogenes:\r\n   ```python\r\n   # Example: Patient is CYP2C19 *1/*2 (intermediate metabolizer)\r\n   response = requests.get(\"https://api.clinpgx.org/v1/allele/CYP2C19*2\")\r\n   allele_function = response.json()\r\n   ```\r\n\r\n2. **Query gene-drug pairs** for medication of interest:\r\n   ```python\r\n   response = requests.get(\"https://api.clinpgx.org/v1/geneDrugPair\",\r\n                          params={\"gene\": \"CYP2C19\", \"drug\": \"clopidogrel\"})\r\n   pair_info = response.json()\r\n   ```\r\n\r\n3. **Retrieve CPIC guideline** for dosing recommendations:\r\n   ```python\r\n   response = requests.get(\"https://api.clinpgx.org/v1/guideline\",\r\n                          params={\"gene\": \"CYP2C19\", \"drug\": \"clopidogrel\"})\r\n   guideline = response.json()\r\n   # Recommendation: Alternative antiplatelet therapy for IM/PM\r\n   ```\r\n\r\n4. **Check drug label** for regulatory guidance:\r\n   ```python\r\n   response = requests.get(\"https://api.clinpgx.org/v1/drugLabel\",\r\n                          params={\"drug\": \"clopidogrel\"})\r\n   label = response.json()\r\n   ```\r\n\r\n### Workflow 2: Gene Panel Analysis\r\n\r\n1. **Get list of pharmacogenes** in clinical panel:\r\n   ```python\r\n   pgx_panel = [\"CYP2C19\", \"CYP2D6\", \"CYP2C9\", \"TPMT\", \"DPYD\", \"SLCO1B1\"]\r\n   ```\r\n\r\n2. **For each gene, retrieve all drug interactions**:\r\n   ```python\r\n   all_interactions = {}\r\n   for gene in pgx_panel:\r\n       response = requests.get(\"https://api.clinpgx.org/v1/geneDrugPair\",\r\n                              params={\"gene\": gene})\r\n       all_interactions[gene] = response.json()\r\n   ```\r\n\r\n3. **Filter for CPIC guideline-level evidence**:\r\n   ```python\r\n   for gene, pairs in all_interactions.items():\r\n       for pair in pairs:\r\n           if pair.get('cpicLevel'):  # Has CPIC guideline\r\n               print(f\"{gene} - {pair['drug']}: {pair['cpicLevel']}\")\r\n   ```\r\n\r\n4. **Generate patient report** with actionable pharmacogenomic findings.\r\n\r\n### Workflow 3: Drug Safety Assessment\r\n\r\n1. **Query drug for PGx associations**:\r\n   ```python\r\n   response = requests.get(\"https://api.clinpgx.org/v1/chemical\",\r\n                          params={\"name\": \"abacavir\"})\r\n   drug_id = response.json()[0]['id']\r\n   ```\r\n\r\n2. **Get clinical annotations**:\r\n   ```python\r\n   response = requests.get(\"https://api.clinpgx.org/v1/clinicalAnnotation\",\r\n                          params={\"drug\": drug_id})\r\n   annotations = response.json()\r\n   ```\r\n\r\n3. **Check for HLA associations** and toxicity risk:\r\n   ```python\r\n   for annotation in annotations:\r\n       if 'HLA' in annotation.get('genes', []):\r\n           print(f\"Toxicity risk: {annotation['phenotype']}\")\r\n           print(f\"Evidence level: {annotation['evidenceLevel']}\")\r\n   ```\r\n\r\n4. **Retrieve screening recommendations** from guidelines and labels.\r\n\r\n### Workflow 4: Research Analysis - Population Pharmacogenomics\r\n\r\n1. **Get allele frequencies** for population comparison:\r\n   ```python\r\n   response = requests.get(\"https://api.clinpgx.org/v1/allele\",\r\n                          params={\"gene\": \"CYP2D6\"})\r\n   alleles = response.json()\r\n   ```\r\n\r\n2. **Extract population-specific frequencies**:\r\n   ```python\r\n   populations = ['European', 'African', 'East Asian', 'Latino']\r\n   frequency_data = {}\r\n   for allele in alleles:\r\n       allele_name = allele['name']\r\n       frequency_data[allele_name] = {\r\n           pop: allele.get(f'{pop}_frequency', 'N/A')\r\n           for pop in populations\r\n       }\r\n   ```\r\n\r\n3. **Calculate phenotype distributions** by population:\r\n   ```python\r\n   # Combine allele frequencies with function to predict phenotypes\r\n   phenotype_dist = calculate_phenotype_frequencies(frequency_data)\r\n   ```\r\n\r\n4. **Analyze implications** for drug dosing in diverse populations.\r\n\r\n### Workflow 5: Literature Evidence Review\r\n\r\n1. **Search for gene-drug pair**:\r\n   ```python\r\n   response = requests.get(\"https://api.clinpgx.org/v1/geneDrugPair\",\r\n                          params={\"gene\": \"TPMT\", \"drug\": \"azathioprine\"})\r\n   pair = response.json()\r\n   ```\r\n\r\n2. **Retrieve all clinical annotations**:\r\n   ```python\r\n   response = requests.get(\"https://api.clinpgx.org/v1/clinicalAnnotation\",\r\n                          params={\"gene\": \"TPMT\", \"drug\": \"azathioprine\"})\r\n   annotations = response.json()\r\n   ```\r\n\r\n3. **Filter by evidence level and publication date**:\r\n   ```python\r\n   high_quality = [a for a in annotations\r\n                   if a['evidenceLevel'] in ['1A', '1B', '2A']]\r\n   ```\r\n\r\n4. **Extract PMIDs** and retrieve full references:\r\n   ```python\r\n   pmids = [a['pmid'] for a in high_quality if 'pmid' in a]\r\n   # Use PubMed skill to retrieve full citations\r\n   ```",
    "Overview": "ClinPGx (Clinical Pharmacogenomics Database) is a comprehensive resource for clinical pharmacogenomics information, successor to PharmGKB. It consolidates data from PharmGKB, CPIC, and PharmCAT, providing curated information on how genetic variation affects medication response. Access gene-drug pairs, clinical guidelines, allele functions, and drug labels for precision medicine applications.",
    "Installation and Setup": "### Python API Access\r\n\r\nThe ClinPGx REST API provides programmatic access to all database resources. Basic setup:\r\n\r\n```bash\r\npip install requests\r\n```\r\n\r\n### API Endpoint\r\n\r\n```python\r\nBASE_URL = \"https://api.clinpgx.org/v1/\"\r\n```\r\n\r\n**Rate Limits**:\r\n- 2 requests per second maximum\r\n- Excessive requests will result in HTTP 429 (Too Many Requests) response\r\n\r\n**Authentication**: Not required for basic access\r\n\r\n**Data License**: Creative Commons Attribution-ShareAlike 4.0 International License\r\n\r\nFor substantial API use, notify the ClinPGx team at api@clinpgx.org",
    "Rate Limiting and Best Practices": "gene_data = cached_query(\r\n    'cyp2d6_cache.json',\r\n    rate_limited_request,\r\n    \"https://api.clinpgx.org/v1/gene/CYP2D6\"\r\n)\r\n```",
    "When to Use This Skill": "This skill should be used when:\r\n\r\n- **Gene-drug interactions**: Querying how genetic variants affect drug metabolism, efficacy, or toxicity\r\n- **CPIC guidelines**: Accessing evidence-based clinical practice guidelines for pharmacogenetics\r\n- **Allele information**: Retrieving allele function, frequency, and phenotype data\r\n- **Drug labels**: Exploring FDA and other regulatory pharmacogenomic drug labeling\r\n- **Pharmacogenomic annotations**: Accessing curated literature on gene-drug-disease relationships\r\n- **Clinical decision support**: Using PharmDOG tool for phenoconversion and custom genotype interpretation\r\n- **Precision medicine**: Implementing pharmacogenomic testing in clinical practice\r\n- **Drug metabolism**: Understanding CYP450 and other pharmacogene functions\r\n- **Personalized dosing**: Finding genotype-guided dosing recommendations\r\n- **Adverse drug reactions**: Identifying genetic risk factors for drug toxicity",
    "Resources": "### scripts/query_clinpgx.py\r\n\r\nPython script with ready-to-use functions for common ClinPGx queries:\r\n\r\n- `get_gene_info(gene_symbol)` - Retrieve gene details\r\n- `get_drug_info(drug_name)` - Get drug information\r\n- `get_gene_drug_pairs(gene, drug)` - Query gene-drug interactions\r\n- `get_cpic_guidelines(gene, drug)` - Retrieve CPIC guidelines\r\n- `get_alleles(gene)` - Get all alleles for a gene\r\n- `get_clinical_annotations(gene, drug, evidence_level)` - Query literature annotations\r\n- `get_drug_labels(drug)` - Retrieve pharmacogenomic drug labels\r\n- `search_variants(rsid)` - Search by variant rsID\r\n- `export_to_dataframe(data)` - Convert results to pandas DataFrame\r\n\r\nConsult this script for implementation examples with proper rate limiting and error handling.\r\n\r\n### references/api_reference.md\r\n\r\nComprehensive API documentation including:\r\n\r\n- Complete endpoint listing with parameters\r\n- Request/response format specifications\r\n- Example queries for each endpoint\r\n- Filter operators and search patterns\r\n- Data schema definitions\r\n- Rate limiting details\r\n- Authentication requirements (if any)\r\n- Troubleshooting common errors\r\n\r\nRefer to this document when detailed API information is needed or when constructing complex queries.",
    "Core Capabilities": "response = requests.get(\"https://api.clinpgx.org/v1/pathway\",\r\n                       params={\"drug\": \"warfarin\"})\r\npathways = response.json()\r\n```\r\n\r\n**Pathway diagrams** show:\r\n- Drug metabolism steps\r\n- Enzymes and transporters involved\r\n- Gene variants affecting each step\r\n- Downstream effects on efficacy/toxicity\r\n- Interactions with other pathways",
    "Important Notes": "### Data Sources and Integration\r\n\r\nClinPGx consolidates multiple authoritative sources:\r\n- **PharmGKB**: Curated pharmacogenomics knowledge base (now part of ClinPGx)\r\n- **CPIC**: Evidence-based clinical implementation guidelines\r\n- **PharmCAT**: Allele calling and phenotype interpretation tool\r\n- **DPWG**: Dutch pharmacogenetics guidelines\r\n- **FDA/EMA labels**: Regulatory pharmacogenomic information\r\n\r\nAs of July 2025, all PharmGKB URLs redirect to corresponding ClinPGx pages.\r\n\r\n### Clinical Implementation Considerations\r\n\r\n- **Evidence levels**: Always check evidence strength before clinical application\r\n- **Population differences**: Allele frequencies vary significantly across populations\r\n- **Phenoconversion**: Consider drug-drug interactions that affect enzyme activity\r\n- **Multi-gene effects**: Some drugs affected by multiple pharmacogenes\r\n- **Non-genetic factors**: Age, organ function, drug interactions also affect response\r\n- **Testing limitations**: Not all clinically relevant alleles detected by all assays\r\n\r\n### Data Updates\r\n\r\n- ClinPGx continuously updates with new evidence and guidelines\r\n- Check publication dates for clinical annotations\r\n- Monitor ClinPGx Blog (https://blog.clinpgx.org/) for announcements\r\n- CPIC guidelines updated as new evidence emerges\r\n- PharmVar provides nomenclature updates for allele definitions\r\n\r\n### API Stability\r\n\r\n- API endpoints are relatively stable but may change during development\r\n- Parameters and response formats subject to modification\r\n- Monitor API changelog and ClinPGx blog for updates\r\n- Consider version pinning for production applications\r\n- Test API changes in development before production deployment"
  }
}

---
name: clinpgx-database
description: "Access ClinPGx pharmacogenomics data (successor to PharmGKB). Query gene-drug interactions, CPIC guidelines, allele functions, for precision medicine and genotype-guided dosing decisions."
---

# ClinPGx Database

## Overview

ClinPGx (Clinical Pharmacogenomics Database) is a comprehensive resource for clinical pharmacogenomics information, successor to PharmGKB. It consolidates data from PharmGKB, CPIC, and PharmCAT, providing curated information on how genetic variation affects medication response. Access gene-drug pairs, clinical guidelines, allele functions, and drug labels for precision medicine applications.

## When to Use This Skill

This skill should be used when:

- **Gene-drug interactions**: Querying how genetic variants affect drug metabolism, efficacy, or toxicity
- **CPIC guidelines**: Accessing evidence-based clinical practice guidelines for pharmacogenetics
- **Allele information**: Retrieving allele function, frequency, and phenotype data
- **Drug labels**: Exploring FDA and other regulatory pharmacogenomic drug labeling
- **Pharmacogenomic annotations**: Accessing curated literature on gene-drug-disease relationships
- **Clinical decision support**: Using PharmDOG tool for phenoconversion and custom genotype interpretation
- **Precision medicine**: Implementing pharmacogenomic testing in clinical practice
- **Drug metabolism**: Understanding CYP450 and other pharmacogene functions
- **Personalized dosing**: Finding genotype-guided dosing recommendations
- **Adverse drug reactions**: Identifying genetic risk factors for drug toxicity

## Installation and Setup

### Python API Access

The ClinPGx REST API provides programmatic access to all database resources. Basic setup:

```bash
pip install requests
```

### API Endpoint

```python
BASE_URL = "https://api.clinpgx.org/v1/"
```

**Rate Limits**:
- 2 requests per second maximum
- Excessive requests will result in HTTP 429 (Too Many Requests) response

**Authentication**: Not required for basic access

**Data License**: Creative Commons Attribution-ShareAlike 4.0 International License

For substantial API use, notify the ClinPGx team at api@clinpgx.org

## Core Capabilities

### 1. Gene Queries

**Retrieve gene information** including function, clinical annotations, and pharmacogenomic significance:

```python
import requests

# Get gene details
response = requests.get("https://api.clinpgx.org/v1/gene/CYP2D6")
gene_data = response.json()

# Search for genes by name
response = requests.get("https://api.clinpgx.org/v1/gene",
                       params={"q": "CYP"})
genes = response.json()
```

**Key pharmacogenes**:
- **CYP450 enzymes**: CYP2D6, CYP2C19, CYP2C9, CYP3A4, CYP3A5
- **Transporters**: SLCO1B1, ABCB1, ABCG2
- **Other metabolizers**: TPMT, DPYD, NUDT15, UGT1A1
- **Receptors**: OPRM1, HTR2A, ADRB1
- **HLA genes**: HLA-B, HLA-A

### 2. Drug and Chemical Queries

**Retrieve drug information** including pharmacogenomic annotations and mechanisms:

```python
# Get drug details
response = requests.get("https://api.clinpgx.org/v1/chemical/PA448515")  # Warfarin
drug_data = response.json()

# Search drugs by name
response = requests.get("https://api.clinpgx.org/v1/chemical",
                       params={"name": "warfarin"})
drugs = response.json()
```

**Drug categories with pharmacogenomic significance**:
- Anticoagulants (warfarin, clopidogrel)
- Antidepressants (SSRIs, TCAs)
- Immunosuppressants (tacrolimus, azathioprine)
- Oncology drugs (5-fluorouracil, irinotecan, tamoxifen)
- Cardiovascular drugs (statins, beta-blockers)
- Pain medications (codeine, tramadol)
- Antivirals (abacavir)

### 3. Gene-Drug Pair Queries

**Access curated gene-drug relationships** with clinical annotations:

```python
# Get gene-drug pair information
response = requests.get("https://api.clinpgx.org/v1/geneDrugPair",
                       params={"gene": "CYP2D6", "drug": "codeine"})
pair_data = response.json()

# Get all pairs for a gene
response = requests.get("https://api.clinpgx.org/v1/geneDrugPair",
                       params={"gene": "CYP2C19"})
all_pairs = response.json()
```

**Clinical annotation sources**:
- CPIC (Clinical Pharmacogenetics Implementation Consortium)
- DPWG (Dutch Pharmacogenetics Working Group)
- FDA (Food and Drug Administration) labels
- Peer-reviewed literature summary annotations

### 4. CPIC Guidelines

**Access evidence-based clinical practice guidelines**:

```python
# Get CPIC guideline
response = requests.get("https://api.clinpgx.org/v1/guideline/PA166104939")
guideline = response.json()

# List all CPIC guidelines
response = requests.get("https://api.clinpgx.org/v1/guideline",
                       params={"source": "CPIC"})
guidelines = response.json()
```

**CPIC guideline components**:
- Gene-drug pairs covered
- Clinical recommendations by phenotype
- Evidence levels and strength ratings
- Supporting literature
- Downloadable PDFs and supplementary materials
- Implementation considerations

**Example guidelines**:
- CYP2D6-codeine (avoid in ultra-rapid metabolizers)
- CYP2C19-clopidogrel (alternative therapy for poor metabolizers)
- TPMT-azathioprine (dose reduction for intermediate/poor metabolizers)
- DPYD-fluoropyrimidines (dose adjustment based on activity)
- HLA-B*57:01-abacavir (avoid if positive)

### 5. Allele and Variant Information

**Query allele function and frequency data**:

```python
# Get allele information
response = requests.get("https://api.clinpgx.org/v1/allele/CYP2D6*4")
allele_data = response.json()

# Get all alleles for a gene
response = requests.get("https://api.clinpgx.org/v1/allele",
                       params={"gene": "CYP2D6"})
alleles = response.json()
```

**Allele information includes**:
- Functional status (normal, decreased, no function, increased, uncertain)
- Population frequencies across ethnic groups
- Defining variants (SNPs, indels, CNVs)
- Phenotype assignment
- References to PharmVar and other nomenclature systems

**Phenotype categories**:
- **Ultra-rapid metabolizer** (UM): Increased enzyme activity
- **Normal metabolizer** (NM): Normal enzyme activity
- **Intermediate metabolizer** (IM): Reduced enzyme activity
- **Poor metabolizer** (PM): Little to no enzyme activity

### 6. Variant Annotations

**Access clinical annotations for specific genetic variants**:

```python
# Get variant information
response = requests.get("https://api.clinpgx.org/v1/variant/rs4244285")
variant_data = response.json()

# Search variants by position (if supported)
response = requests.get("https://api.clinpgx.org/v1/variant",
                       params={"chromosome": "10", "position": "94781859"})
variants = response.json()
```

**Variant data includes**:
- rsID and genomic coordinates
- Gene and functional consequence
- Allele associations
- Clinical significance
- Population frequencies
- Literature references

### 7. Clinical Annotations

**Retrieve curated literature annotations** (formerly PharmGKB clinical annotations):

```python
# Get clinical annotations
response = requests.get("https://api.clinpgx.org/v1/clinicalAnnotation",
                       params={"gene": "CYP2D6"})
annotations = response.json()

# Filter by evidence level
response = requests.get("https://api.clinpgx.org/v1/clinicalAnnotation",
                       params={"evidenceLevel": "1A"})
high_evidence = response.json()
```

**Evidence levels** (from highest to lowest):
- **Level 1A**: High-quality evidence, CPIC/FDA/DPWG guidelines
- **Level 1B**: High-quality evidence, not yet guideline
- **Level 2A**: Moderate evidence from well-designed studies
- **Level 2B**: Moderate evidence with some limitations
- **Level 3**: Limited or conflicting evidence
- **Level 4**: Case reports or weak evidence

### 8. Drug Labels

**Access pharmacogenomic information from drug labels**:

```python
# Get drug labels with PGx information
response = requests.get("https://api.clinpgx.org/v1/drugLabel",
                       params={"drug": "warfarin"})
labels = response.json()

# Filter by regulatory source
response = requests.get("https://api.clinpgx.org/v1/drugLabel",
                       params={"source": "FDA"})
fda_labels = response.json()
```

**Label information includes**:
- Testing recommendations
- Dosing guidance by genotype
- Warnings and precautions
- Biomarker information
- Regulatory source (FDA, EMA, PMDA, etc.)

### 9. Pathways

**Explore pharmacokinetic and pharmacodynamic pathways**:

```python
# Get pathway information
response = requests.get("https://api.clinpgx.org/v1/pathway/PA146123006")  # Warfarin pathway
pathway_data = response.json()

# Search pathways by drug
response = requests.get("https://api.clinpgx.org/v1/pathway",
                       params={"drug": "warfarin"})
pathways = response.json()
```

**Pathway diagrams** show:
- Drug metabolism steps
- Enzymes and transporters involved
- Gene variants affecting each step
- Downstream effects on efficacy/toxicity
- Interactions with other pathways

## Query Workflow

### Workflow 1: Clinical Decision Support for Drug Prescription

1. **Identify patient genotype** for relevant pharmacogenes:
   ```python
   # Example: Patient is CYP2C19 *1/*2 (intermediate metabolizer)
   response = requests.get("https://api.clinpgx.org/v1/allele/CYP2C19*2")
   allele_function = response.json()
   ```

2. **Query gene-drug pairs** for medication of interest:
   ```python
   response = requests.get("https://api.clinpgx.org/v1/geneDrugPair",
                          params={"gene": "CYP2C19", "drug": "clopidogrel"})
   pair_info = response.json()
   ```

3. **Retrieve CPIC guideline** for dosing recommendations:
   ```python
   response = requests.get("https://api.clinpgx.org/v1/guideline",
                          params={"gene": "CYP2C19", "drug": "clopidogrel"})
   guideline = response.json()
   # Recommendation: Alternative antiplatelet therapy for IM/PM
   ```

4. **Check drug label** for regulatory guidance:
   ```python
   response = requests.get("https://api.clinpgx.org/v1/drugLabel",
                          params={"drug": "clopidogrel"})
   label = response.json()
   ```

### Workflow 2: Gene Panel Analysis

1. **Get list of pharmacogenes** in clinical panel:
   ```python
   pgx_panel = ["CYP2C19", "CYP2D6", "CYP2C9", "TPMT", "DPYD", "SLCO1B1"]
   ```

2. **For each gene, retrieve all drug interactions**:
   ```python
   all_interactions = {}
   for gene in pgx_panel:
       response = requests.get("https://api.clinpgx.org/v1/geneDrugPair",
                              params={"gene": gene})
       all_interactions[gene] = response.json()
   ```

3. **Filter for CPIC guideline-level evidence**:
   ```python
   for gene, pairs in all_interactions.items():
       for pair in pairs:
           if pair.get('cpicLevel'):  # Has CPIC guideline
               print(f"{gene} - {pair['drug']}: {pair['cpicLevel']}")
   ```

4. **Generate patient report** with actionable pharmacogenomic findings.

### Workflow 3: Drug Safety Assessment

1. **Query drug for PGx associations**:
   ```python
   response = requests.get("https://api.clinpgx.org/v1/chemical",
                          params={"name": "abacavir"})
   drug_id = response.json()[0]['id']
   ```

2. **Get clinical annotations**:
   ```python
   response = requests.get("https://api.clinpgx.org/v1/clinicalAnnotation",
                          params={"drug": drug_id})
   annotations = response.json()
   ```

3. **Check for HLA associations** and toxicity risk:
   ```python
   for annotation in annotations:
       if 'HLA' in annotation.get('genes', []):
           print(f"Toxicity risk: {annotation['phenotype']}")
           print(f"Evidence level: {annotation['evidenceLevel']}")
   ```

4. **Retrieve screening recommendations** from guidelines and labels.

### Workflow 4: Research Analysis - Population Pharmacogenomics

1. **Get allele frequencies** for population comparison:
   ```python
   response = requests.get("https://api.clinpgx.org/v1/allele",
                          params={"gene": "CYP2D6"})
   alleles = response.json()
   ```

2. **Extract population-specific frequencies**:
   ```python
   populations = ['European', 'African', 'East Asian', 'Latino']
   frequency_data = {}
   for allele in alleles:
       allele_name = allele['name']
       frequency_data[allele_name] = {
           pop: allele.get(f'{pop}_frequency', 'N/A')
           for pop in populations
       }
   ```

3. **Calculate phenotype distributions** by population:
   ```python
   # Combine allele frequencies with function to predict phenotypes
   phenotype_dist = calculate_phenotype_frequencies(frequency_data)
   ```

4. **Analyze implications** for drug dosing in diverse populations.

### Workflow 5: Literature Evidence Review

1. **Search for gene-drug pair**:
   ```python
   response = requests.get("https://api.clinpgx.org/v1/geneDrugPair",
                          params={"gene": "TPMT", "drug": "azathioprine"})
   pair = response.json()
   ```

2. **Retrieve all clinical annotations**:
   ```python
   response = requests.get("https://api.clinpgx.org/v1/clinicalAnnotation",
                          params={"gene": "TPMT", "drug": "azathioprine"})
   annotations = response.json()
   ```

3. **Filter by evidence level and publication date**:
   ```python
   high_quality = [a for a in annotations
                   if a['evidenceLevel'] in ['1A', '1B', '2A']]
   ```

4. **Extract PMIDs** and retrieve full references:
   ```python
   pmids = [a['pmid'] for a in high_quality if 'pmid' in a]
   # Use PubMed skill to retrieve full citations
   ```

## Rate Limiting and Best Practices

### Rate Limit Compliance

```python
import time

def rate_limited_request(url, params=None, delay=0.5):
    """Make API request with rate limiting (2 req/sec max)"""
    response = requests.get(url, params=params)
    time.sleep(delay)  # Wait 0.5 seconds between requests
    return response

# Use in loops
genes = ["CYP2D6", "CYP2C19", "CYP2C9"]
for gene in genes:
    response = rate_limited_request(
        "https://api.clinpgx.org/v1/gene/" + gene
    )
    data = response.json()
```

### Error Handling

```python
def safe_api_call(url, params=None, max_retries=3):
    """API call with error handling and retries"""
    for attempt in range(max_retries):
        try:
            response = requests.get(url, params=params, timeout=10)

            if response.status_code == 200:
                return response.json()
            elif response.status_code == 429:
                # Rate limit exceeded
                wait_time = 2 ** attempt  # Exponential backoff
                print(f"Rate limit hit. Waiting {wait_time}s...")
                time.sleep(wait_time)
            else:
                response.raise_for_status()

        except requests.exceptions.RequestException as e:
            print(f"Attempt {attempt + 1} failed: {e}")
            if attempt == max_retries - 1:
                raise
            time.sleep(1)
```

### Caching Results

```python
import json
from pathlib import Path

def cached_query(cache_file, api_func, *args, **kwargs):
    """Cache API results to avoid repeated queries"""
    cache_path = Path(cache_file)

    if cache_path.exists():
        with open(cache_path) as f:
            return json.load(f)

    result = api_func(*args, **kwargs)

    with open(cache_path, 'w') as f:
        json.dump(result, f, indent=2)

    return result

# Usage
gene_data = cached_query(
    'cyp2d6_cache.json',
    rate_limited_request,
    "https://api.clinpgx.org/v1/gene/CYP2D6"
)
```

## PharmDOG Tool

PharmDOG (formerly DDRx) is ClinPGx's clinical decision support tool for interpreting pharmacogenomic test results:

**Key features**:
- **Phenoconversion calculator**: Adjusts phenotype predictions for drug-drug interactions affecting CYP2D6
- **Custom genotypes**: Input patient genotypes to get phenotype predictions
- **QR code sharing**: Generate shareable patient reports
- **Flexible guidance sources**: Select which guidelines to apply (CPIC, DPWG, FDA)
- **Multi-drug analysis**: Assess multiple medications simultaneously

**Access**: Available at https://www.clinpgx.org/pharmacogenomic-decision-support

**Use cases**:
- Clinical interpretation of PGx panel results
- Medication review for patients with known genotypes
- Patient education materials
- Point-of-care decision support

## Resources

### scripts/query_clinpgx.py

Python script with ready-to-use functions for common ClinPGx queries:

- `get_gene_info(gene_symbol)` - Retrieve gene details
- `get_drug_info(drug_name)` - Get drug information
- `get_gene_drug_pairs(gene, drug)` - Query gene-drug interactions
- `get_cpic_guidelines(gene, drug)` - Retrieve CPIC guidelines
- `get_alleles(gene)` - Get all alleles for a gene
- `get_clinical_annotations(gene, drug, evidence_level)` - Query literature annotations
- `get_drug_labels(drug)` - Retrieve pharmacogenomic drug labels
- `search_variants(rsid)` - Search by variant rsID
- `export_to_dataframe(data)` - Convert results to pandas DataFrame

Consult this script for implementation examples with proper rate limiting and error handling.

### references/api_reference.md

Comprehensive API documentation including:

- Complete endpoint listing with parameters
- Request/response format specifications
- Example queries for each endpoint
- Filter operators and search patterns
- Data schema definitions
- Rate limiting details
- Authentication requirements (if any)
- Troubleshooting common errors

Refer to this document when detailed API information is needed or when constructing complex queries.

## Important Notes

### Data Sources and Integration

ClinPGx consolidates multiple authoritative sources:
- **PharmGKB**: Curated pharmacogenomics knowledge base (now part of ClinPGx)
- **CPIC**: Evidence-based clinical implementation guidelines
- **PharmCAT**: Allele calling and phenotype interpretation tool
- **DPWG**: Dutch pharmacogenetics guidelines
- **FDA/EMA labels**: Regulatory pharmacogenomic information

As of July 2025, all PharmGKB URLs redirect to corresponding ClinPGx pages.

### Clinical Implementation Considerations

- **Evidence levels**: Always check evidence strength before clinical application
- **Population differences**: Allele frequencies vary significantly across populations
- **Phenoconversion**: Consider drug-drug interactions that affect enzyme activity
- **Multi-gene effects**: Some drugs affected by multiple pharmacogenes
- **Non-genetic factors**: Age, organ function, drug interactions also affect response
- **Testing limitations**: Not all clinically relevant alleles detected by all assays

### Data Updates

- ClinPGx continuously updates with new evidence and guidelines
- Check publication dates for clinical annotations
- Monitor ClinPGx Blog (https://blog.clinpgx.org/) for announcements
- CPIC guidelines updated as new evidence emerges
- PharmVar provides nomenclature updates for allele definitions

### API Stability

- API endpoints are relatively stable but may change during development
- Parameters and response formats subject to modification
- Monitor API changelog and ClinPGx blog for updates
- Consider version pinning for production applications
- Test API changes in development before production deployment

## Common Use Cases

### Pre-emptive Pharmacogenomic Testing

Query all clinically actionable gene-drug pairs to guide panel selection:

```python
# Get all CPIC guideline pairs
response = requests.get("https://api.clinpgx.org/v1/geneDrugPair",
                       params={"cpicLevel": "A"})  # Level A recommendations
actionable_pairs = response.json()
```

### Medication Therapy Management

Review patient medications against known genotypes:

```python
patient_genes = {"CYP2C19": "*1/*2", "CYP2D6": "*1/*1", "SLCO1B1": "*1/*5"}
medications = ["clopidogrel", "simvastatin", "escitalopram"]

for med in medications:
    for gene in patient_genes:
        response = requests.get("https://api.clinpgx.org/v1/geneDrugPair",
                               params={"gene": gene, "drug": med})
        # Check for interactions and dosing guidance
```

### Clinical Trial Eligibility

Screen for pharmacogenomic contraindications:

```python
# Check for HLA-B*57:01 before abacavir trial
response = requests.get("https://api.clinpgx.org/v1/geneDrugPair",
                       params={"gene": "HLA-B", "drug": "abacavir"})
pair_info = response.json()
# CPIC: Do not use if HLA-B*57:01 positive
```

## Additional Resources

- **ClinPGx website**: https://www.clinpgx.org/
- **ClinPGx Blog**: https://blog.clinpgx.org/
- **API documentation**: https://api.clinpgx.org/
- **CPIC website**: https://cpicpgx.org/
- **PharmCAT**: https://pharmcat.clinpgx.org/
- **ClinGen**: https://clinicalgenome.org/
- **Contact**: api@clinpgx.org (for substantial API use)