PharmcatParser
Converts long-read pharmacogenomics output — PharmCAT, pbStarPhase, or a plain Gene/Diplotype table — into the JSON format Geneyx Analysis consumes for PGx reporting.
Install it next to your own PacBio or ONT pipeline, run it on the output, and upload the result to Geneyx.
pip install PharmcatParser
pharmcat-parser HG002.pharmcat.report.json HG002.pbstarphase.json --output-json HG002.geneyx-pgx-results.json
Output format
A JSON array, one entry per gene, with exactly four fields:
[
{ "Id": "CYP2C19", "Name": "CYP2C19", "StarAllele": "*1/*1", "Activity": "Normal Metabolizer" }
]
Id/Name— the gene symbol. Both are required; the Geneyx report keys its result set onIdand filters onName.StarAllele— the diplotype (*1/*2).Activity— the phenotype / metaboliser status (Normal Metabolizer), ornullwhen it is not known.
These names are matched case-sensitively on the Geneyx side. Do not rename them.
A second file, <output>.provenance.json, is written alongside the result. It
records the caller versions, the mapping-table versions used, per-gene warnings,
and any term that had no Geneyx mapping. It is not part of the upload contract —
it exists so a report can be traced back to what produced it.
Supported inputs
| Input | Detected by | Provides |
|---|---|---|
*.pharmcat.report.json |
name or pharmcatVersion |
diplotypes, phenotypes, tool + data versions |
*.pharmcat.phenotype.json |
name or geneReports |
diplotypes, phenotypes |
*.pbstarphase.json |
name or gene_details |
diplotypes only, for more genes than PharmCAT reports |
*.csv / *.json table |
fallback | Gene + Diplotype (+ optional Phenotype) |
The minimal table is the upload format: a header with Gene and Diplotype
is enough. Column names are matched loosely (gene, geneSymbol, symbol;
diplotype, genotype, starAllele).
Why two files are better than one
PharmCAT only reports genes that have a CPIC or DPWG guideline. In a PacBio HG002 run, pbStarPhase called 35 genes and PharmCAT reported 22. Four of the dropped genes — NAT2, CYP1A2, CYP2A13, CYP2C8 — are covered by the Geneyx PGx report. Passing the pbStarPhase summary alongside the PharmCAT output recovers them; they arrive with a diplotype and no phenotype.
Where both files describe the same gene, PharmCAT wins: it normalises
PharmVar sub-alleles (*4.015) to the core alleles (*4) that Geneyx uses.
Merging rules
- One entry per gene. PharmCAT emits a gene report per phenotype source, so the same 22 genes appear under both CPIC and DPWG. One source is preferred and the other is consulted only as a fallback — see below.
- Unmapped terms are dropped, not passed through. A PharmCAT phenotype with
no Geneyx equivalent yields
Activity: nullplus a warning in the provenance file, rather than an unrecognised term that looks valid to the report. - Genotype-guided genes (IFNL3, VKORC1) take their
StarAllelefrom the rewritten allele names rather than from the phenotype. - HLA alleles are truncated to two fields (
*01:01:01:01→*01:01). - Single-allele genes (MT-RNR1) are not written as a diplotype.
Choosing a phenotype source
PharmCAT phenotypes come from two guideline bodies, CPIC and DPWG, and they do not always agree. Pick one:
pharmcat-parser HG002.pharmcat.report.json --phenotype-source DPWG
The default is CPIC (the first entry of phenotype_source_preference in
gene_rules.json). The choice only reorders the sources — it never narrows the
output. When the chosen source has no usable phenotype for a gene, the next
source in the default order is used instead, and the substitution is recorded:
{ "Id": "CYP2B6", "phenotypeSource": "CPIC",
"warnings": ["no usable phenotype from DPWG; taken from CPIC"] }
"No usable phenotype" covers three cases: the source reported none at all
(HG002 CPIC: CYP3A4, CYP4F2, VKORC1), it reported a no-call token such as
n/a (HG002 DPWG: CYP2B6), or its term has no Geneyx mapping yet (HG002 DPWG:
DPYD 2.0 (Normal Metabolizer)).
The source selection affects Activity only — StarAllele is identical either
way, since both sources describe the same call. The preference actually used is
written to the provenance file as phenotypeSourcePreference.
Mapping tables
The clinical vocabulary lives in PharmcatParser/Mappings/ as versioned JSON:
| File | Contains |
|---|---|
gene_rules.json |
structural rules — source preference, HLA/sub-allele handling |
phenotype_terms.json |
PharmCAT phenotype term → Geneyx Activity term |
genotype_terms.json |
allele/diplotype rewrites for genotype-guided genes |
The term tables are incomplete. Entries with a
nulltarget still need filling from the approved mapping sheet. Run the parser and readunmappedTermsin the provenance file to see exactly which terms are missing for your data.
Development
pip install -e .
pytest PharmcatParser/Test/Test_PharmcatParser.py -v
Test fixtures are real PacBio output for HG002, a public GIAB reference sample. No patient data belongs in this repository.
Metadata
Release files for PharmcatParser 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pharmcatparser-0.1.0.tar.gz | 22.5 kB | Without provenance | Details for pharmcatparser-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pharmcatparser-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for pharmcatparser-0.1.0-py3-none-any.whl |
Total release size: 49.9 kB
Release files / pharmcatparser-0.1.0.tar.gz
| Download URL | pharmcatparser-0.1.0.tar.gz |
|---|---|
| Size | 22.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f6c8a959fc66d8447bab59a16f86fa9e6dcc69644052ac0f46ff9fb1da197d93
|
|
BLAKE2b-256 checksum How to use checksums |
c585d6fc087aea0f9dd25075ec6cdbec6551f11de57ea78463e964c2778f07ff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.13
|
Release files / pharmcatparser-0.1.0-py3-none-any.whl
| Download URL | pharmcatparser-0.1.0-py3-none-any.whl |
|---|---|
| Size | 27.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
02854421a3b9cd659bca4fcf96727a79925235339b0062771e1b4a0815e2eed6
|
|
BLAKE2b-256 checksum How to use checksums |
87162165afd9c2c3bd0d25206e34bf2ab8cd949829a2c8c0ecdfe149d452009b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.13
|
Security for PharmcatParser 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.