alterlab-clinpgx
Access ClinPGx pharmacogenomics data (the successor to PharmGKB) to query gene-drug interactions, CPIC/DPWG dosing guidelines, drug labels, and pharmacogene records. Use when interpreting pharmacogenes (CYP2D6, CYP2C19, TPMT, DPYD, SLCO1B1), looking up genotype-guided drug dosing
Install
npx skills add https://github.com/AlterLab-IEU/AlterLab-Academic-Skills/tree/main/skills/databases/alterlab-clinpgx
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alterlab-ieu-alterlab-academic-skills@llmmart
git clone https://github.com/AlterLab-IEU/AlterLab-Academic-Skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole alterlab-ieu/alterlab-academic-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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 |
| Literature search — guideline publications, review papers, full citations and abstracts | alterlab-pubmed |
Hand-off rule. When the request matches a row above, open your answer by naming that skill by its exact id (for example alterlab-clinvar) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.
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 fromresponse.json()["data"]; onstatus == "fail",datais{"errors": [...]}(e.g. "No results matching criteria"). - Query-param convention (verified): genes filter on
relatedGenes.symbol(the.nameform fails), while chemicals/drugs filter onrelatedChemicals.name—relatedChemicals.symbolsilently returnsstatus: "fail"with zero results. Thegenecollection takes?symbol=, thechemicalcollection takes?name=, andvariantaccepts?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
- Resolve identifiers — Convert gene symbols / rsIDs to ClinPGx accession
IDs via collection endpoints with
symbol=parameters. - Query the relevant resource —
gene,chemical,guidelineAnnotation,summaryAnnotation,variantAnnotation,variant,label, orpathway. There is no/alleleresource — use PharmVar (https://www.pharmvar.org/) for star-allele definitions and population frequencies. - Derive gene-drug relationships — From guideline annotations
(
relatedGenes.symbolfor genes,relatedChemicals.namefor drugs), or the/report/pair/{firstObjId}/{secondObjId}/{resultType}endpoint. - Filter by evidence level — Prefer levels 1A/1B/2A for clinical use; confirm field names against the live OpenAPI spec.
- 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
- 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/
- PharmVar (star alleles): https://www.pharmvar.org/
- ClinGen: https://clinicalgenome.org/
- Contact: api@clinpgx.org (for substantial API use)
Files (alterlab-academic-skills)
-
evals
-
evals.json 3.9 KB
Loading…
-
-
references
-
api_reference.md 18.9 KB
Loading… -
endpoints-and-capabilities.md 8.9 KB
Loading… -
query-workflows.md 6.5 KB
Loading… -
rate-limiting-and-error-handling.md 2.8 KB
Loading…
-
-
scripts
-
query_clinpgx.py 17.5 KB
Loading…
-
-
SKILL.md 9 KB
--- name: alterlab-clinpgx description: Access ClinPGx pharmacogenomics data (the successor to PharmGKB) to query gene-drug interactions, CPIC/DPWG dosing guidelines, drug labels, and pharmacogene records. Use when interpreting pharmacogenes (CYP2D6, CYP2C19, TPMT, DPYD, SLCO1B1), looking up genotype-guided drug dosing, checking PGx drug-safety associations (e.g. HLA-B*57:01 and abacavir), or supporting precision medicine and clinical pharmacogenomics decisions. For star-allele definitions/frequencies see PharmVar; for germline/somatic variant pathogenicity see alterlab-clinvar. Part of the AlterLab Academic Skills suite. license: MIT allowed-tools: Read WebFetch Bash(curl:*) Bash(python:*) Bash(uv run:*) compatibility: Keyless ClinPGx (PharmGKB) API for basic access (no authentication required) metadata: skill-author: AlterLab version: "1.0.1" last_updated: "2026-09-23" --- # 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` | | Literature search — guideline publications, review papers, full citations and abstracts | `alterlab-pubmed` | **Hand-off rule.** When the request matches a row above, open your answer by naming that skill by its exact id (for example `alterlab-clinvar`) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work. ## Setup and Access Essentials Only `requests` is needed. Run the helper script (or any snippet) with an ephemeral dependency — no venv to manage: ```bash 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 - **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/ - **PharmVar** (star alleles): https://www.pharmvar.org/ - **ClinGen**: https://clinicalgenome.org/ - **Contact**: api@clinpgx.org (for substantial API use)
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.