SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsalterlab-clinpgx

alterlab-clinpgx

Data & analytics

View repository

Updated 10-15 19:56

About this skill

ClinPGx Database

Overview

ClinPGx (Clinical Pharmacogenomics Database) is a comprehensive resource for clinical pharmacogenomics, the 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.

When to Use This Skill

Use this skill for:

  • Gene-drug interactions — how variants affect drug metabolism, efficacy, or toxicity
  • CPIC guidelines — evidence-based clinical practice guidelines for pharmacogenetics
  • Allele information — allele function, frequency, and phenotype data
  • Drug labels — FDA and other regulatory pharmacogenomic labeling
  • Pharmacogenomic annotations — curated literature on gene-drug-disease relationships
  • Clinical decision support — PharmDOG for phenoconversion and custom genotype interpretation
  • Precision medicine / personalized dosing — genotype-guided dosing recommendations
  • Drug metabolism — CYP450 and other pharmacogene functions
  • Adverse drug reactions — genetic risk factors for drug toxicity

Does NOT Trigger

Scenario Use Instead
Germline/somatic variant pathogenicity or ClinVar review status alterlab-clinvar
Population allele frequencies for a variant (gnomAD v4) alterlab-gnomad
Drug–drug interactions or general pharmacology with no genetic component alterlab-drugbank
FDA adverse-event reports, recalls, or full-text label search alterlab-fda

Setup and Access Essentials

Only requests is needed. Run the helper script (or any snippet) with an ephemeral dependency — no venv to manage:

uv run --with requests python scripts/query_clinpgx.py
# or, inside an existing project venv: uv pip install requests

Base URL: https://api.clinpgx.org/v1/data/ — the legacy api.pharmgkb.org host was turned off on 2026-07-20, so older PharmGKB scripts must switch hostnames (paths are unchanged).

  • Resource addressing: ClinPGx resources are addressed by ClinPGx accession IDs in the path (e.g. gene CYP2D6 = PA128, CYP2C9 = PA126), not by gene symbols or rsIDs. To resolve a symbol or rsID, query the collection endpoint with parameters (e.g. GET /v1/data/gene?symbol=CYP2D6, GET /v1/data/variant?symbol=rs4244285) and read the accession ID from the response.
  • Response envelope (verified): every response is a JSON object {"status": "success"|"fail", "data": [...]} — the payload is never a bare list. Read results from response.json()["data"]; on status == "fail", data is {"errors": [...]} (e.g. "No results matching criteria").
  • Query-param convention (verified): genes filter on relatedGenes.symbol (the .name form fails), while chemicals/drugs filter on relatedChemicals.name — relatedChemicals.symbol silently returns status: "fail" with zero results. The gene collection takes ?symbol=, the chemical collection takes ?name=, and variant accepts ?symbol=/?name=.
  • Rate limits: 2 requests per second maximum; excessive requests return HTTP 429. Implement a ~500ms delay between requests.
  • Authentication: Not required for basic access.
  • Data license: Creative Commons Attribution-ShareAlike 4.0 International.
  • For substantial API use, notify the ClinPGx team at api@clinpgx.org.

Core Workflow

  1. Resolve identifiers — Convert gene symbols / rsIDs to ClinPGx accession IDs via collection endpoints with symbol= parameters.
  2. Query the relevant resource — gene, chemical, guidelineAnnotation, summaryAnnotation, variantAnnotation, variant, label, or pathway. There is no /allele resource — use PharmVar (https://www.pharmvar.org/) for star-allele definitions and population frequencies.
  3. Derive gene-drug relationships — From guideline annotations (relatedGenes.symbol for genes, relatedChemicals.name for drugs), or the /report/pair/{firstObjId}/{secondObjId}/{resultType} endpoint.
  4. Filter by evidence level — Prefer levels 1A/1B/2A for clinical use; confirm field names against the live OpenAPI spec.
  5. Respect rate limits — Throttle, retry on 429 with backoff, and cache.

For ready-made functions with rate limiting and error handling, see scripts/query_clinpgx.py.

Routing Guidance

  • Need the exact code for a resource (gene, chemical, gene-drug pair, CPIC guideline, allele/PharmVar, variant, clinical annotation, label, pathway)? Read references/endpoints-and-capabilities.md.
  • Doing an end-to-end task (clinical decision support, gene-panel analysis, drug-safety assessment, population pharmacogenomics, literature review) or a common use case? Read references/query-workflows.md.
  • Need robust API plumbing (rate limiting, retries, caching)? Read references/rate-limiting-and-error-handling.md.
  • Need full endpoint/parameter/schema details? Read references/api_reference.md.

References

  • references/api_reference.md — Complete endpoint listing, request/response formats, filter operators, data schemas, rate-limit details, and troubleshooting.
  • references/endpoints-and-capabilities.md — Worked code for all nine capability areas (gene, drug/chemical, gene-drug pair, CPIC guidelines, allele/PharmVar, variant, clinical annotations, drug labels, pathways), including key pharmacogenes and evidence-level definitions.
  • references/query-workflows.md — Five end-to-end workflows (decision support, gene panel, drug safety, population pharmacogenomics, literature review) plus common use cases (pre-emptive testing, medication therapy management, trial eligibility).
  • references/rate-limiting-and-error-handling.md — Reusable helpers for rate limiting, retries with exponential backoff, and result caching.

PharmDOG Tool

PharmDOG (formerly DDRx) is ClinPGx's clinical decision support tool for interpreting pharmacogenomic test results. Features: phenoconversion calculator (adjusts phenotype for drug-drug interactions affecting CYP2D6), custom genotype input, QR-code report sharing, selectable guidance sources (CPIC, DPWG, FDA), and multi-drug analysis. Access: https://www.clinpgx.org/pharmacogenomic-decision-support

Important Notes

Data sources — ClinPGx consolidates PharmGKB (now part of ClinPGx), CPIC, PharmCAT, DPWG, and FDA/EMA labels. As of July 2025, all PharmGKB URLs redirect to corresponding ClinPGx pages.

Clinical considerations — Always check evidence strength before clinical application; allele frequencies vary significantly across populations; account for phenoconversion (drug-drug interactions) and multi-gene effects; non-genetic factors (age, organ function) also affect response; not all clinically relevant alleles are detected by all assays.

Data updates / API stability — ClinPGx updates continuously; check publication dates and the ClinPGx Blog (https://blog.clinpgx.org/). API endpoints are relatively stable but may change during development — pin versions and test in development before production.

Additional Resources