BMI 530: Software Development in Biomedical Informatics
A pharmacogenomics prototype that maps a reported star-allele diplotype to a metabolizer phenotype, then matches that phenotype to published gene–drug recommendations. It covers CYP2C19, CYP2D6 and CYP2B6, and answers for every drug CPIC covers for those genes — 2,159 recommendations over 18,678 diplotypes, built from CPIC v1.61.0. The written analysis focuses on six psychotropics: paroxetine, fluvoxamine, venlafaxine, vortioxetine, escitalopram and sertraline.
What it deliberately does not do is combine genes into a composite score or rank drugs best-to-worst. That layer is what distinguishes a commercial combinatorial test from the guidelines underneath it, and it is also the layer the evidence does not support. The engine reports the cited recommendation, names the genes that decided it, links the guideline, and stops — including when the guideline's answer is "no recommendation", which is reported as a result rather than hidden as a blank.
Important
Educational prototype — not for clinical use or medical decisions.
A packaged build needs nothing installed — no Java, no Python, and is located under releases.
It starts its own engine on the loopback interface, picks a free port, and stops the engine when the window closes. To build it, see Build Distributions.
You could also run the engine application directly from source rather than using a packaged build.
| Python | 3.11 or newer |
| Java | JDK 17 or newer (client only) |
| Everything else | pip install -r requirements.txt |
JavaFX is fetched by Apache Maven; nothing to install by hand.
The database is generated, not committed. Building it needs network access to
api.cpicpgx.org.
# Optional: check the live column names before trusting the schema
python -m pgx.query.cpic --inspect
python -m pgx.query.cpic \
--genes CYP2C19 CYP2D6 CYP2B6 \
--cpic-version v1.61.0 \
--pharmvar-version "via CPIC v1.61.0 (API import)" \
--out data/cypgx.dbPin the versions. They are stamped into the database's meta table and
surface in every report's provenance block, which is what makes a result
reproducible months later.
Command line — one patient at a time, or a CSV batch:
Example:
python -m pgx.cli --db data/cypgx.db --gene CYP2C19=*2/*5 --gene CYP2D6=*4/*4 --prettypython -m pgx.cli --db data/cypgx.db --batch cohort.csv --out reports.jsonlHTTP service — FastAPI on loopback:
CYPGX_DB=data/cypgx.db python -m pgx.service --port 8000
# PowerShell: $env:CYPGX_DB = "data/cypgx.db"| Endpoint | |
|---|---|
GET /health |
status, row counts, source versions |
GET /genes |
loaded genes and their diplotype counts |
GET /genes/{gene}/diplotypes?q=&limit= |
searched, never listed whole |
GET /drugs?all= |
answerable drugs, or all of them |
POST /report |
{"diplotypes": {"CYP2C19": "*2/*5"}} |
Desktop client — JavaFX, talks to the service over HTTP. Build with Apache Maven:
cd client
mvn -q clean compile javafx:runcompile matters: the fonts and stylesheet are resources, and javafx:run
alone will not copy them. The client opens on an offline stub if it finds no
engine, so it runs with nothing else started.
bash packaging/build.sh # any Linux or macOS (UNIX-based) systempowershell -ExecutionPolicy Bypass -File packaging\build.ps1 # Windows only| Output | Needs installed | Runs on |
|---|---|---|
dist/CYPGxEngine-portable/ |
Java 17+ | Windows, Linux, Apple Silicon |
dist/CYPGxEngine/ |
nothing | the platform it was built on |
Both carry their own frozen engine and a copy of the knowledge base, and both start the engine themselves. Neither cross-builds: run the script on the platform you are targeting.
pgx/
models.py the report contract — schema 1.1
core/engine.py resolution and matching. Imports pgx.models and nothing else
query/cpic.py build step: CPIC API -> SQLite
api/main.py FastAPI wrapper
service.py runnable entry point, frozen by PyInstaller
cli.py single and batch reports
notation.py GeT-RM -> CPIC diplotype notation
activity.py CYP2D6 activity-score parsing and banding
panel.py masking a diplotype to what a limited assay would report
frequency.py Hardy-Weinberg priors and phenotype posteriors
client/ JavaFX client (Java 17, JavaFX 21)
packaging/ build scripts and PyInstaller spec
TBA.
No network and no data/cypgx.db required, the suite builds its own fixture.
Diplotypes from the CDC's GeT-RM reference panel resolved 652 of 663 (98.3%), or 99.4% excluding the seven where GeT-RM itself reports no consensus. Activity-score banding was checked against CPIC across all 16,836 CYP2D6 diplotypes. A rebuild five weeks later against CPIC v1.61.0 changed no phenotype and no recommendation for the six drugs in scope.
A reported diplotype is not an observation of a genome. It is an observation of
whichever alleles the assay interrogated, with *1 filled in everywhere else —
so *1/*1 from a two-allele panel and *1/*1 from sequencing print
identically and mean different things. Two experiments measure that gap against
GeT-RM, whose true diplotypes are known.
Phenotype accuracy when each true diplotype is masked down to what a given panel would have reported, then re-resolved. The posterior is deliberately not exposed through the report contract: on these results it would improve one gene of three and degrade another.
Write
Alleles combine independently within an individual, so diplotype probabilities follow Hardy-Weinberg:
With
An assay is a deterministic many-to-one map. Masking under panel *1, so the likelihood is an indicator, not a
density:
Bayes therefore reduces to conditioning on a set: the posterior is the prior restricted to the preimage of the observation, renormalised.
Phenotype is itself a deterministic map
Two limits fall out of this and are asserted as tests. With *1/*1, the preimage
Brier and log loss are both strictly proper: expected score is minimised by reporting your actual beliefs, so a forecast cannot win by hedging. Brier is the headline because it is bounded.
A confidently wrong point call costs 2.0. The same call costs log loss infinity, which is why that metric is floored — and why, once floored, it is largely counting misses.
Propriety carries one consequence worth stating. Under a strictly proper rule, a correctly specified prior makes the posterior the Bayes-optimal forecast, and no other predictor — the point call included — can beat it in expectation. So CYP2B6 scoring worse than the point call is evidence that the prior is misspecified for this cohort, not that the method fails. GeT-RM was assembled to be rich in variant alleles and is not drawn from the frequencies the prior describes.
Nothing here is fitted: 652 samples against 16,836 CYP2D6 diplotypes leaves nothing to fit that would not be fitting noise. The prior is CPIC's published allele frequencies, the likelihood is the definition of the assay, and no parameter is estimated from data.
A panel induces a partition of diplotype space; a narrower panel is a coarser partition; the Brier gain tracks how much phenotype uncertainty survives the observation. It is largest where the partition is coarsest and vanishes when the mask becomes injective.
- Gene–drug recommendations, diplotype–phenotype tables and allele functions: CPIC / ClinPGx, retrieved through their public REST API. Guideline text is reproduced verbatim and attributed in every report.
- Reference diplotypes: CDC GeT-RM.
- Typefaces: Cascadia Mono and Courier Prime, both SIL OFL 1.1 — see
client/src/main/resources/fonts/NOTICE.txt.
This engine was built with assistance from Claude (Anthropic), used as a coding agent with GitHub Copilot, and a writing assistant (generally assisting in populating this README.md from a drafted MS) across sessions between October and November 2026.
Responsibility for the correctness of what is here is mine.
